@@ -0,0 +1,158 @@
1+---
2+layout: post
3+title: Building a Production-Ready OpenCode Configuration from Scratch
4+description: A deep dive into cost optimization, workflows, and skills for OpenCode.
5+---
6+
7+# Building a Production-Ready OpenCode Configuration from Scratch
8+
9+Setting up an AI coding assistant isn't just about picking a model and starting to code. After spending time configuring OpenCode from the ground up, I learned that a thoughtful setup can save you money, improve code quality, and create a more disciplined development workflow.
10+
11+Here's how I built a comprehensive OpenCode configuration that balances cost efficiency with powerful capabilities.
12+
13+## The Foundation: Global Rules and Workflow
14+
15+The first step was creating a global `AGENTS.md` file at `~/.config/opencode/AGENTS.md`. This isn't just documentation—it's the behavioral contract for all AI interactions.
16+
17+### Core Principles
18+
19+I established several non-negotiable rules:
20+- Professional tone (no "You're absolutely right!" responses)
21+- No emojis or AI-speak
22+- Documentation-first approach
23+- No auto-commits without explicit approval
24+- Always work within the current repo's root
25+
26+### The Six-Phase Workflow
27+
28+The real breakthrough was implementing a structured development workflow:
29+
30+1. **Plan** - Use Plan mode for gathering information and creating detailed plans
31+2. **Validate** - Verify assumptions before building
32+3. **Build** - Implement with discipline to return to Plan if issues arise
33+4. **Review** - Use the built-in `/review` command (a hidden gem I discovered)
34+5. **Document** - Update AGENTS.md, README.md, and inline docs
35+6. **Complete** - Provide verification evidence before claiming "done"
36+
37+This workflow prevents the common AI pitfall of pushing through problems blindly.
38+
39+## Configuration: opencode.json Optimization
40+
41+The `opencode.json` file is where the magic happens. Here's what I learned about model selection and cost optimization.
42+
43+### Model Selection Strategy
44+
45+I started with Claude Sonnet 4.5 at $3.00/$15.00 per 1M tokens, but the costs were adding up fast. After analyzing usage patterns, I discovered that cache reads were dominating my bill—534M cache reads in typical usage.
46+
47+The breakthrough came with Gemini 3 Flash at $0.50/$3.00 per 1M tokens. This represented an 80% cost reduction while maintaining quality for most coding tasks.
48+
49+### Smart Configuration Choices
50+
51+```json
52+{
53+ "provider": "opencode-zen",
54+ "default_model": "opencode/gemini-3-flash",
55+ "small_model": "opencode/gpt-5-nano",
56+ "instructions": [
57+ "CONTRIBUTING.md",
58+ "docs/guidelines.md",
59+ ".cursor/rules/*.md"
60+ ],
61+ "agent_temperatures": {
62+ "plan": 0.1,
63+ "build": 0.3
64+ }
65+}
66+```
67+
68+Key insights:
69+- Use a free model (GPT 5 Nano) for simple tasks like title generation
70+- Auto-load project documentation with the `instructions` array
71+- Different temperatures for different modes (lower for planning, higher for creative building)
72+- Git permission rules requiring approval for destructive operations
73+
74+## Skills: The Secret Weapon
75+
76+The skills ecosystem through `skills.sh` was a game-changer. I installed seven carefully chosen skills:
77+
78+### Core Skills Installed
79+
80+- **systematic-debugging** - Methodical approach to problem-solving
81+- **verification-before-completion** - QA discipline before claiming "done"
82+- **writing-plans** - Structured planning methodology
83+- **commit-work** - Git commit discipline and best practices
84+- **crafting-effective-readmes** - Documentation standards
85+- **mermaid-diagrams** - Visual documentation tools
86+- **writing-clearly-and-concisely** - Communication improvement
87+
88+### Installation Strategy
89+
90+I used the `npx skills -g` command to install skills globally, then copied them as actual files (not symlinks) for portability across machines. This ensures the configuration works identically on any development environment.
91+
92+## Hidden Features and Discoveries
93+
94+### The /review Command
95+
96+OpenCode has a built-in `/review` command that I wish I'd discovered earlier. It can review changes at different scopes:
97+- `review changes` - Uncommitted changes (default)
98+- `review changes commit` - Last commit
99+- `review changes branch` - Current branch vs main
100+- `review changes pr` - Pull request changes
101+
102+This eliminates the need for manual code review workflows.
103+
104+### Model Naming Convention
105+
106+OpenCode Zen uses a specific naming convention with the "opencode/" prefix. This caught me off guard initially—make sure to use names like `opencode/gemini-3-flash`, not just `gemini-3-flash`.
107+
108+## Cost Analysis and Optimization
109+
110+The numbers tell the story. My original configuration would have cost roughly $50-80 per month for heavy usage. The optimized setup reduced this to $10-15 per month—a 75-80% savings.
111+
112+### Cost Factors to Consider
113+
114+- **Input tokens** - Your code and prompts
115+- **Output tokens** - AI responses
116+- **Cache reads** - Often the biggest cost factor
117+- **Model capabilities** - Balance cost vs. quality needs
118+
119+The key insight: cache reads can dominate your bill. Choose models with favorable cache pricing, and Gemini 3 Flash excels here.
120+
121+## Final Directory Structure
122+
123+```
124+~/.config/opencode/
125+├── AGENTS.md # Global rules and workflow (63 lines)
126+├── opencode.json # Optimized configuration
127+├── agents/
128+│ └── writer.md # Specialized subagents
129+└── skills/ # Portable skill library
130+ ├── commit-work/
131+ ├── crafting-effective-readmes/
132+ ├── mermaid-diagrams/
133+ ├── systematic-debugging/
134+ ├── verification-before-completion/
135+ ├── writing-clearly-and-concisely/
136+ └── writing-plans/
137+```
138+
139+## Lessons Learned
140+
141+1. **Start with discipline** - Rules and workflow matter more than model choice
142+2. **Monitor costs actively** - Usage patterns reveal optimization opportunities
143+3. **Skills are force multipliers** - The ecosystem provides battle-tested methodologies
144+4. **Documentation is configuration** - AGENTS.md shapes AI behavior as much as JSON settings
145+5. **Hidden features exist** - Explore built-in commands like `/review`
146+
147+## Next Steps
148+
149+This configuration provides a solid foundation, but it's designed to evolve. As new models become available and costs change, the structure supports easy updates. The workflow ensures quality remains high regardless of the underlying technology.
150+
151+The investment in setup pays dividends in every subsequent coding session. Professional AI assistance isn't just about having access to models—it's about creating systems that amplify your capabilities while maintaining discipline and cost control.
152+
153+## Sources
154+
155+- OpenCode documentation and configuration reference
156+- skills.sh ecosystem and skill library
157+- OpenCode Zen pricing analysis and model comparisons
158+- Personal configuration testing and cost optimization experiments