5745
Sc
sacenox.github.io / files
sacenox.github.io / _posts / 2026-01-31-when-opencode-cant-see-your-docs.md
2.1 KB
1--- 2layout: post 3title: cautionary-tale-about-the-agents-md-migration 4description: "A quick cautionary tale about missing docs and the five-minute opencode.json fix." 5--- 6 7# When OpenCode Can't See Your Docs 8 9I just spent 20 minutes watching Claude flail around like a lost tourist. 10 11## The Setup 12 13You know that feeling when you've got everything organized perfectly? I had this beautiful `.agent-docs/` folder full of debugging guides, programming principles, writing tips - the works. All cross-referenced in `AGENTS.md` with a nice little index. 14Then I fired up OpenCode and asked Claude to help with a bug. 15 16## The Confusion 17 18"Read the systematic debugging guide first," I said, pointing at the file path. 19Claude squinted at the screen. "I don't see that file. Let me search for debugging patterns instead..." 20Then it started making stuff up. Generic debugging advice pulled from training data instead of my carefully crafted, battle-tested process. It was like watching someone reinvent the wheel when I'd already built a Ferrari. 21I tried again. "It's in `.agent-docs/debugging/01-overview-iron-law.md`." 22More confusion. Claude could see the current directory files just fine, but anything in my docs folder might as well have been on Mars. 23 24## The Lightbulb 25 26That's when it hit me - OpenCode only knows about files you tell it about. I'd spent all this time organizing documentation but forgot the most basic step: letting the tool actually access it. 27Five minutes later, I created `opencode.json`: 28 29```json 30{ 31 "instructions": [ 32 ".agent-docs/**/*.md", 33 ".agent-docs/**/*.ts", 34 ".agent-docs/**/*.sh" 35 ] 36} 37``` 38 39## The Relief 40 41Restarted OpenCode. Asked the same question. 42This time Claude immediately said, "Let me read the systematic debugging guide first" and pulled up the exact file. No more generic advice. No more reinventing wheels. Just my actual process, refined through months of real debugging sessions. 43 44## The Takeaway 45 46Your docs are only as good as your tool's ability to find them. Spend five minutes on `opencode.json` and save yourself hours of watching Claude guess at what you've already figured out.