OpenCode System Prompt: Configure and Test Project Instructions

OpenCode is an open-source terminal-based AI coding assistant that can connect to multiple model providers, including Anthropic, OpenAI, and locally hosted models such as Qwen. Like other coding tools, it accepts project-level instructions that shape how the AI behaves across sessions in that directory. Tools like fenbs keep the project rules and decisions that should survive a model change or a team handoff, outside any one session.

The exact file name and format OpenCode uses for project instructions can change between releases. Always check the OpenCode documentation↗ (opens in a new tab) for the current configuration method before setting up a new project.

Project-level vs. global instructions in OpenCode

Most terminal coding tools distinguish between global instructions (which apply to all projects on a machine) and project-level instructions (which live in the project directory). OpenCode follows the same pattern. A global instruction might set your preferred language or output style; a project instruction adds the context specific to that codebase -- its stack, its conventions, and the rules the team has agreed on.

Put project-specific rules in the project directory so they travel with the code. Put only truly universal preferences in the global configuration. Mixing the two leads to instructions that apply in the wrong places.

Qwen models and message format

When you configure OpenCode to use a Qwen model -- either through a cloud provider that offers Qwen or a local instance -- the model expects instructions in the ChatML format. ChatML uses special tokens to separate the system turn from the conversation:

<|im_start|>system
Your instruction here.<|im_end|>
<|im_start|>user
User message here.<|im_end|>
<|im_start|>assistant

In practice, OpenCode handles this formatting for you when it constructs the API request. What you write in your instructions file is plain text. The issue arises when you run a Qwen model outside OpenCode -- for example, directly through the Ollama API or a local inference server -- and the template is not applied automatically. In that case the system turn can be silently ignored or merged into the user message.

For more on how system prompts vary by model and interface, system prompt vs. user prompt covers the structural difference. The post on OpenCode vs. Claude Code compares the two tools' approaches to project instructions.

What to put in your OpenCode instructions

Effective project instructions for a coding tool cover three areas: the stack (language, framework, key libraries), the conventions the team follows (naming, file organization, patterns to avoid), and the boundaries of what the AI should change on its own versus ask about.

• Language and framework: "This project uses TypeScript and Next.js 16. Use ESM imports."
• Style rules: "Follow the existing file structure. Do not add new top-level folders without asking."
• Testing: "Write tests in Vitest. Place them alongside the source file, not in a separate tests/ folder."
• Off-limits: "Do not change the database schema. Ask before adding a dependency."
• Context: "This is an internal tool for a five-person team. Prioritize readability over cleverness."

Keep the instruction file short enough to read in two minutes. A long file that nobody maintains becomes worse than no file. Record the reasons behind unusual rules so a future developer (or AI) understands why the rule exists.

Testing that your instructions applied

After setting up your instructions, open a new OpenCode session and ask a question whose answer would look different without them. If you specified TypeScript, ask it to write a utility function and check the output. If you prohibited a pattern, ask it to solve a problem where that pattern would be a natural choice.

If the model ignores an instruction, check two things. First, whether the instruction is specific enough -- "avoid complexity" is not testable, but "do not use class-based components" is. Second, check whether the model you are using reliably follows system-level instructions or tends to treat them as suggestions. Some smaller models follow instructions less consistently.

Common issues

The most common issue is stale instructions that no longer match the project. A rule written when the project started can become wrong after a refactor. Review the instructions file when significant decisions change, and update it the same day.

• Instructions in the wrong scope: a project-specific rule placed in the global config applies everywhere.
• Model-specific format problems: instructions written for one provider's model may not translate cleanly to another.
• Conflicting rules: "be concise" and "always explain your reasoning" will produce inconsistent output.
• No test after setup: instructions look reasonable on paper but fail for edge cases you did not test.

How to do this with fenbs

1. Create a free account. Start with a personal kanban board for this project.
2. Add a task for setting up the OpenCode instructions. In the plan, note the model provider, the key rules, and which developer approved them.
3. Write the agreed project rules as Decisions and rules in fenbs. Include who decided each rule and why, so the next developer understands the context.
4. Connect OpenCode or another coding tool to fenbs over MCP from Integrations. The connected tool reads your project rules and current task list at the start of each session.
5. When a rule changes, update the Decision in fenbs and record why. The old version stays in History so the team can trace when the change happened.

For a look at ready-to-use instruction examples, system prompt examples has patterns worth adapting. The general prompt engineering guide covers the principles behind writing instructions that hold up.