make a web page that looks just like the attached claude-code-best-practices.pdf original URL: https://www.anthropic.com/engineering/claude-code-best-practices but has this content for open-code: "Opencode: Best Practices for Terminal-Native AI Coding Engineering at SST Published June 28, 2025 Opencode is a command line tool for agentic coding. This post covers tips and tricks that have proven effective for using Opencode across various codebases, languages, and environments. We recently released Opencode, an open-source command line tool for agentic coding. Developed by SST, Opencode gives engineers a more native way to integrate Claude and other AI models into their coding workflows—particularly for those with Claude Max subscriptions who want to maximize their investment. Opencode is intentionally terminal-based and unopinionated, providing close to raw model access without forcing specific workflows. This design philosophy creates a flexible, customizable, scriptable, and safe power tool. While powerful, this flexibility presents a learning curve for engineers new to agentic coding tools—at least until they develop their own best practices. This post outlines general patterns that have proven effective, both for SST's internal teams and for external engineers using Opencode across various codebases, languages, and environments. Nothing in this list is set in stone nor universally applicable; consider these suggestions as starting points. We encourage you to experiment and find what works best for you! Looking for more detailed information? The comprehensive documentation at opencode.ai/docs covers all the features mentioned in this post and provides additional examples, implementation details, and advanced techniques. 1. Customize your setup Opencode is an agentic coding assistant that automatically pulls context into prompts. This context gathering consumes time and tokens, but you can optimize it through environment tuning. a. Create AGENTS.md files AGENTS.md is a special file that Opencode automatically pulls into context when starting a conversation. This makes it an ideal place for documenting: Common bash commands Core files and utility functions Code style guidelines Testing instructions Repository etiquette (e.g., branch naming, merge vs. rebase, etc.) Developer environment setup (e.g., pyenv use, which compilers work) Any unexpected behaviors or warnings particular to the project Other information you want Opencode to remember There's no required format for AGENTS.md files. We recommend keeping them concise and human-readable. For example: # Project Context This is an SST v3 monorepo with TypeScript The project uses bun workspaces # Bash commands - bun test: Run all tests - bun build: Build the project # Code style - Use ES modules (import/export) syntax, not CommonJS (require) - Destructure imports when possible (eg. import { foo } from 'bar') # Workflow - Run tests with: bun test - PR messages should follow conventional commits You can place AGENTS.md files in several locations: The root of your repo, or wherever you run opencode from (the most common usage). Name it AGENTS.md and check it into git so that you can share it across sessions and with your team Any parent of the directory where you run opencode. This is most useful for monorepos Any child of the directory where you run opencode. Opencode will pull in AGENTS.md files on demand when you work with files in child directories When you run the /init command, Opencode will automatically generate an AGENTS.md for you. b. Tune your AGENTS.md files Your AGENTS.md files become part of Opencode's prompts, so they should be refined like any frequently used prompt. A common mistake is adding extensive content without iterating on its effectiveness. Take time to experiment and determine what produces the best instruction following from the model. You can add content to your AGENTS.md manually or use the /init command to generate a starting template. Many engineers frequently update AGENTS.md to document commands, files, and style guidelines while coding, then include AGENTS.md changes in commits so team members benefit as well. At SST, we occasionally run AGENTS.md files through prompt improvement tools and often tune instructions (e.g. adding emphasis with "IMPORTANT" or "YOU MUST") to improve adherence. c. Configure your authentication By default, Opencode supports multiple authentication methods. For Claude Max subscribers, OAuth authentication provides the simplest setup: # OAuth authentication (recommended for Claude Max users) opencode auth login # Select your provider interactively # Alternative: Direct API key configuration opencode auth login # Enter API key when prompted Authentication credentials are stored securely in ~/.local/share/opencode/auth.json. Opencode also supports environment variables for all major providers (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.). d. If using GitHub, install the gh CLI Opencode knows how to use the gh CLI to interact with GitHub for creating issues, opening pull requests, reading comments, and more. Without gh installed, Opencode can still use git commands through the bash tool. 2. Give Opencode more tools Opencode has access to your shell environment, where you can build up sets of convenience scripts and functions for it just like you would for yourself. It can also leverage more complex tools through MCP. a. Use Opencode with bash tools Opencode inherits your bash environment, giving it access to all your tools. While Opencode knows common utilities like unix tools and gh, it won't know about your custom bash tools without instructions: Tell Opencode the tool name with usage examples Tell Opencode to run --help to see tool documentation Document frequently used tools in AGENTS.md b. Use Opencode with MCP Opencode functions as an MCP client, connecting to any number of MCP servers to access their tools. Configuration is done through .opencode.json: { "mcpServers": { "example-server": { "type": "stdio", "command": "path/to/mcp-server", "args": [], "env": [] } } } MCP servers can be configured in: Project config (.opencode.json in your project directory) Global config (~/.opencode.json) Environment-specific configurations c. Use custom commands For repeated workflows—debugging loops, log analysis, etc.—store prompt templates in Markdown files within the command folders. These become available through the slash commands menu when you type /. Custom commands are stored in: User commands: ~/.config/opencode/commands/ Project commands: .opencode/commands/ Custom commands can include variables like $ISSUE_NUMBER or $AUTHOR_NAME to pass parameters from command invocation. For example, here's a custom command for analyzing GitHub issues: # Fetch Context for Issue $ISSUE_NUMBER RUN gh issue view $ISSUE_NUMBER --json title,body,comments RUN git log --grep="$ISSUE_NUMBER" --oneline Putting the above content into .opencode/commands/analyze-issue.md makes it available as the /project:analyze-issue command. You could then use /project:analyze-issue 1234 to have Opencode analyze issue #1234. 3. Try common workflows Opencode doesn't impose a specific workflow, giving you the flexibility to use it how you want. Within the space this flexibility affords, several successful patterns for effectively using Opencode have emerged across our community of users: a. Explore, plan, code, commit This versatile workflow suits many problems: Ask Opencode to read relevant files, images, or URLs, providing either general pointers ("read the file that handles logging") or specific filenames ("read logging.py"), but explicitly tell it not to write any code just yet. Ask Opencode to make a plan for how to approach a specific problem. Since Opencode focuses on practical coding assistance, ask it to outline the specific steps and files that need modification. Ask Opencode to implement its solution in code. This is also a good place to ask it to explicitly verify the reasonableness of its solution as it implements pieces of the solution. Ask Opencode to commit the result and create a pull request. If relevant, this is also a good time to have Opencode update any READMEs or changelogs with an explanation of what it just did. Steps #1-#2 are crucial—without them, Opencode tends to jump straight to coding a solution. While sometimes that's what you want, asking Opencode to research and plan first significantly improves performance for problems requiring deeper analysis upfront. b. Write tests, commit; code, iterate, commit This is an SST-favorite workflow for changes that are easily verifiable with unit, integration, or end-to-end tests. Test-driven development (TDD) becomes even more powerful with agentic coding: Ask Opencode to write tests based on expected input/output pairs. Be explicit about the fact that you're doing test-driven development so that it avoids creating mock implementations. Tell Opencode to run the tests and confirm they fail. Explicitly telling it not to write any implementation code at this stage is often helpful. Ask Opencode to commit the tests when you're satisfied with them. Ask Opencode to write code that passes the tests, instructing it not to modify the tests. Tell Opencode to keep going until all tests pass. Ask Opencode to commit the code once you're satisfied with the changes. Opencode performs best when it has a clear target to iterate against—a visual mock, a test case, or another kind of output. c. Write code, screenshot result, iterate Similar to the testing workflow, you can provide Opencode with visual targets: Give Opencode a way to take browser screenshots (e.g., with the Puppeteer MCP server, or manually copy/paste screenshots). Give Opencode a visual mock by copying/pasting or providing an image file path. Ask Opencode to implement the design in code, take screenshots of the result, and iterate until its result matches the mock. Ask Opencode to commit when you're satisfied. Like humans, Opencode's outputs tend to improve significantly with iteration. While the first version might be good, after 2-3 iterations it will typically look much better. d. Session-based development Opencode's session management allows you to maintain multiple parallel development efforts: # Start a new session for a feature opencode # Work on feature A # In another terminal, start a different session opencode # Work on feature B # Switch between sessions # Use Ctrl+A to access session switcher Sessions persist across restarts and can be shared via generated URLs for collaboration or debugging. e. Codebase Q&A When onboarding to a new codebase, use Opencode for learning and exploration. You can ask Opencode the same sorts of questions you would ask another engineer on the project when pair programming: How does logging work? How do I make a new API endpoint? What does async move { ... } do on line 134 of foo.rs? What edge cases does CustomerOnboardingFlowImpl handle? Why are we calling foo() instead of bar() on line 333? At SST, using Opencode in this way has become our core onboarding workflow, significantly improving ramp-up time and reducing load on other engineers. f. Use Opencode to interact with git Opencode can effectively handle many git operations through its bash tool integration: Searching git history to answer questions like "What changes made it into v1.2.3?" Writing commit messages based on staged changes Handling complex git operations like reverting files, resolving conflicts Creating branches with descriptive names g. Use Opencode to interact with GitHub With the gh CLI installed, Opencode can manage GitHub interactions: Creating pull requests with appropriate descriptions Reading and responding to code review comments Fixing failing builds or linter warnings Categorizing and triaging open issues This eliminates the need to remember gh command line syntax while automating routine tasks. h. Use Opencode with configuration files Opencode excels at working with various configuration formats. It can read, understand, and modify: JSON configuration files YAML/TOML settings Environment files Package manifests 4. Optimize your workflow The suggestions below apply across all workflows: a. Be specific in your instructions Opencode's success rate improves significantly with more specific instructions, especially on first attempts. For example: PoorGoodadd tests for foo.pywrite a new test case for foo.py, covering the edge case where the user is logged out. use the existing test pattern from test_bar.pyfix the bugfix the null pointer exception in getUserName() that occurs when the session is expiredadd a widgetimplement a calendar widget following the pattern in DatePicker.tsx, allowing month selection with forward/back navigation Opencode can infer intent, but specificity leads to better alignment with expectations. b. Leverage the leader key system Opencode uses a leader key system to avoid terminal conflicts: Press Ctrl+X followed by another key for shortcuts Ctrl+X then n creates a new session Ctrl+K opens the command palette Ctrl+A switches between sessions This approach keeps your terminal's native shortcuts intact while providing quick access to Opencode features. c. Manage context effectively Opencode includes automatic context management: Auto-compact: When approaching token limits, Opencode automatically summarizes previous context Session persistence: All conversations stored in SQLite for continuity File tracking: Visual indicators show which files have been modified d. Use custom commands for repetition Create reusable commands for common tasks: # Create a command for your daily standup echo "Summarize my git commits from yesterday" > ~/.config/opencode/commands/standup.md # Use it with: /user:standup e. Configure provider fallbacks Set up multiple providers to ensure continuous availability: { "providers": { "preferred": ["anthropic", "openai"], "fallback": "openai" } } f. Optimize for your environment Opencode respects your terminal environment: Custom shell configuration via .opencode.json Environment variable support for all settings Working directory awareness Git repository detection 5. Use prompt mode for automation Opencode includes a prompt mode for non-interactive contexts: # Single prompt execution opencode -p "Update all imports to use ES modules" # With specific output format opencode -p "List all TODO comments" -f json # Restrict to specific tools opencode -p "Format this file" --allowedTools Edit a. Use Opencode for code review Prompt mode can provide automated code reviews: opencode -p "Review the staged changes for code style and potential bugs" b. Use Opencode for documentation Generate or update documentation automatically: opencode -p "Update the README with the latest API changes" 6. Leverage multi-session workflows Beyond standalone usage, some of the most powerful applications involve running multiple Opencode sessions: a. Parallel development Run multiple sessions for independent features: Open multiple terminal windows or tabs Start Opencode in each with different working directories Work on separate features simultaneously Each session maintains its own context and history b. Collaborative debugging Share sessions for pair programming: Generate a shareable session URL Share with teammates for debugging assistance Both can view the conversation history and context c. Context isolation Use separate sessions for different concerns: One session for frontend work Another for backend API development A third for database migrations This prevents context pollution and keeps each session focused. What are your tips and best practices for working with Opencode? Tag @SST so we can see what you're building! Acknowledgements Written by the SST Documentation Team. This work draws upon best practices from across the broader Opencode user community, whose creative approaches and workflows continue to inspire us. Special thanks to the engineers who have adopted Opencode with their Claude Max subscriptions and contributed valuable insights that helped shape these recommendations."