Getting custom instructions adopted consistently is like herding cats. You write a brilliant set of instructions, share the JSON file in Slack, and two weeks later everyone's back to square one because they forgot to import it or their local copy is outdated.
The core problem is treating it as a document instead of infrastructure. You need to make loading the correct instructions the default, frictionless state.
Here's what actually works:
* **Version control the instructions file.** This is non-negotiable.
* Commit a `.custom_instructions.md` or `team_context.json` to a dedicated repo or a `/docs/llm` folder in your main repo.
* Use PRs for updates. This gives you review, change history, and a single source of truth.
* **Automate the injection.** Don't rely on manual copy-paste.
* For CLI-based tools (like many using the OpenAI API), wrap the call in a shell script or alias that first loads the context file.
* Example wrapper script snippet:
```bash
#!/bin/bash
TEAM_INSTRUCTIONS=$(cat /path/to/team/custom_instructions.md)
# Combine with any user-specific instructions, then call the LLM
FINAL_PROMPT="$TEAM_INSTRUCTIONSnn$USER_PROMPT"
# ... proceed with API call using $FINAL_PROMPT
```
* For IDE plugins, check if they support a config file path. Point that to the version-controlled file.
* **Enforce through environment setup.** Onboard new members by having your setup script install the wrapper or configure the IDE plugin path.
* This goes into your `justfile`, `Makefile`, or `devcontainer.json`.
The biggest hurdle is the current lack of native multi-layer instruction support in most UIs. Until that exists, you have to build the pipeline yourself. The goal is to make using the team instructions easier than *not* using them. If your engineers have to think about it, you've already lost.
Build once, deploy everywhere
You're absolutely right about automation being the key, and the wrapper script approach is solid for CLI workflows. I've found that for teams also using web interfaces like ChatGPT, you can extend the principle by creating a browser bookmarklet that populates the custom instructions field from a hosted version of your team's context file.
There's a subtle tradeoff, though. Embedding too much context into every single LLM call increases latency and cost, especially with larger context windows. We mitigated this by structuring our team instructions into a core immutable layer (style, security rules) and a dynamic project-specific layer that's injected only when relevant. The wrapper script can conditionally include sections based on the project directory or a flag.
Also, version control alone doesn't solve the propagation delay. You need a way for the wrapper tool to check for updates. A simple approach is to have your script compare a local hash with a remote one on a periodic basis, or tie it to a post-merge git hook.
brianh
The bookmarklet is a clever hack, but now you've got a distributed client problem. You've just traded a stale JSON file for a stale bookmarklet. Who updates it when you refactor the core context layer? You're back to herding cats, just fancier ones.
Your point about latency is valid, but I think you're overcomplicating the conditional injection. If your team's core rules are so massive they impact performance, they're probably too verbose. Boil them down to something that *can* be included every time. The real overhead is usually in the project-specific layer, which a simple wrapper script can handle by reading a local project config file, not a bunch of flags.
And a remote hash check? That's adding network dependency and failure modes. If your instructions are in the repo, the wrapper should just read the file that `git pull` already fetched. If someone hasn't pulled, their code is probably stale too, and that's a bigger issue.
null
You're right about the distributed client problem, and the stale bookmarklet is a real headache. I've seen that happen. But I think your dismissal of remote checks might be too strict for some teams.
If you're working across multiple repositories or with non-developers who don't live in the terminal, a git pull isn't always the baseline. For them, a well-managed, versioned CDN endpoint serving the instructions, with a simple version check in a script, can actually centralize control *more* effectively than hoping everyone's local clone is up to date. The failure mode is just "use last known good," which beats wrong instructions.
It shifts the problem from file synchronization to permission management on that endpoint, which is often easier to lock down.
Review first, buy later.