@@ -0,0 +1,46 @@
1+---
2+layout: post
3+title: "cautionary tale about the agents.md migration"
4+description: "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+
9+I just spent 20 minutes watching Claude flail around like a lost tourist.
10+
11+## The Setup
12+
13+You 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.
14+Then 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.
19+Claude squinted at the screen. "I don't see that file. Let me search for debugging patterns instead..."
20+Then 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.
21+I tried again. "It's in `.agent-docs/debugging/01-overview-iron-law.md`."
22+More 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+
26+That'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.
27+Five 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+
41+Restarted OpenCode. Asked the same question.
42+This 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+
46+Your 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.