How to code with AI
Use OpenCode to work through a small coding task: define the expected behavior, configure permissions, make the change and review the results.
1. Establish a starting point
Choose a repository you are allowed to share with the model provider. Before opening the agent, inspect your working tree and identify the project's existing build and test commands. Save your own work using your normal version-control process; do not ask an agent to discard unrelated changes.
Pick one task with observable behavior. For example: “An empty search query returns all entries; change it to return no entries and keep non-empty search behavior unchanged.” Record where that behavior is implemented and how the project currently tests it.
The useful result is an accepted change with evidence, not merely a generated patch. For a refactor, specify the behavior that must remain unchanged. For a bug, specify the input and output that reproduce it.
2. Connect one model and set permissions
Follow the installation guide, then start opencode. Use /connect to configure a provider and /models to choose an available model. Confirm a small connection before adding optional plugins or MCP servers. Provider usage may be billed separately from the free client.
For this first task, ask before shell commands by merging the following setting into opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"bash": "ask"
}
}This setting governs the shell tool; it is not a complete sandbox or a policy for every tool. Check the permissions reference and your existing project/global settings. If your client rejects this setting, check the configuration format supported by your installed version.
If authentication or a model request fails, use the connection checklist. Repeatedly reinstalling the client does not establish that a key or billing account is valid.
3. Describe the project's actual conventions
Create or update the repository's AGENTS.md with facts you have checked. Name the existing test command, the relevant directories and any files the task must not change. Do not claim the project uses a library or framework without inspecting it.
## Project instructions
- Use the repository's existing build and test commands.
- Inspect nearby code before changing a shared interface.
- Keep the change limited to the reported search behavior.
- Do not add a dependency without explaining why it is necessary.
- Report checks that could not be run.The rules documentation explains how OpenCode discovers instructions. Instructions guide the agent; they do not prove that every output follows them.
4. Reproduce, change and verify
Ask the agent to locate the relevant function and show how the current behavior is tested. If the repository has a suitable test framework, add a failing behavior test before changing the implementation. Confirm that it fails for the intended reason rather than an unrelated setup error.
Then request the smallest change that satisfies the task. Run the targeted check and the repository's required validation. Inspect the actual output: an unexecuted test or a skipped build is not a pass.
An example task prompt:
Find the search implementation and its existing tests. Reproduce the empty-query
behavior. Change only that behavior, preserve non-empty queries, and run the
relevant checks. Show the resulting diff and any remaining uncertainty.Expected evidence includes the changed files, the behavior before and after, and the executed checks. The exact patch depends on your codebase.
5. Review before accepting
Read the diff for scope, behavior and maintainability. Check for removed error handling, unrequested dependencies, hidden fallback behavior and tests that merely repeat the implementation. Review security-sensitive changes with the appropriate expertise for your project.
If the result is wrong, return to a concrete reproduction and acceptance criterion. Break a large task into smaller parts when the current diff is difficult to review. More instructions or a more expensive model do not guarantee a correct result.
Once the change is understood and required checks pass, commit it according to your project's conventions. Keep failed checks and integration limitations visible in the handoff.
Match the model to a task
Start with a model you can connect and evaluate. Use model settings to select it explicitly, and compare Zen model prices or your provider's rates before a long run. For Claude access, the model setup guide explains provider-specific IDs.
Ask a small code-navigation question before asking for a multi-file change. If it fails because files are unavailable or the environment is broken, changing models may not fix the cause. Check available tools and the repository context first.
Plan a change before editing
For an unfamiliar codebase, use the Plan agent to inspect the implementation and identify affected files. Confirm the behavior you want to keep, then switch to an editing workflow. Keep the task small enough that you can review every changed file.
In the TUI, reference the relevant files and supply the error output that reproduces the problem. If working inside an editor, the IDE integration can help bring the active file into the workflow. Supplying relevant context is more useful than pasting an entire repository into a prompt.
A useful task description includes the input, expected output, files likely involved, and a test command. “Improve the whole application” leaves all four undefined. Split it into concrete changes such as preserving an existing route while fixing an empty-search result.
Where AI-generated changes need closer review
| Failure pattern | What to inspect | How to respond |
|---|---|---|
| A test passes but behavior changed elsewhere | Callers, edge cases and removed assertions | Reproduce the affected case and add a behavior check |
| The patch adds an unnecessary dependency | Existing project utilities and deployment constraints | Ask for an implementation using current dependencies |
| The agent claims a check passed without output | Actual command, exit status and skipped steps | Run the required check and retain its result |
| The task grows into an unrelated rewrite | Diff scope and acceptance criteria | Separate unrelated edits from the intended fix |
| The model invents a configuration option | The applicable reference and installed tooling | Verify the field in the configuration reference |
Project instructions in rules and explicit permissions help define the workflow. They do not replace reading the final diff.
Automate a stable step
Once a manual workflow works, capture a repeated prompt in custom commands, or use the CLI for a bounded scripted task. Add MCP tools only when the task needs an external system, with the appropriate credentials and access.
For repository events, review the GitHub or GitLab integration before granting automation write access. Run the repository's checks independently of the model's final message and preserve logs for failed runs.
Work with a team
Keep shared instructions and project configuration in version control, with secrets stored separately. Agree on which commands require review and what evidence accompanies a proposed change. The enterprise documentation provides a starting point for organization requirements.
If you use session sharing, inspect the content before sharing it. For model access failures, isolate the account, model, network and quota using the connection checklist. A repeatable team workflow includes a way to reproduce problems as well as a way to generate changes.
Keep formatting and access rules explicit
Use the project's established formatters instead of mixing a behavior change with unrelated formatting. Review policy settings alongside permissions when the task has access constraints. Connect accounts through the provider guide; project instructions should not contain credentials.
For a concrete model setup, follow the Fable guide. If the workflow does not fit your preferred interface, use the Claude Code comparison or Cursor comparison to evaluate alternatives on the same task.