xonecas.io
5745
Sc

sacenox.github.io / commit 8bfb4fe

feat: add blog post on opencode documentation visibility and cautionary tale

xonecas2026-01-31 8bfb4feff8b25aae91efda7d775b8c509921fe35 parent 9520abb

8 files changed

_posts/2026-01-31-ditching-skills-for-agents-md.md+2−0
@@ -48,6 +48,8 @@ I kept all the debugging content but broke it into logical chunks. The writing g
4848
4949 Early testing shows agents find answers faster and use fewer tokens. They're not loading irrelevant sections or getting lost in long files. The debugging workflow especially feels smoother - agents can follow the phases without getting overwhelmed.
5050
51+Don't forget to update your `opencode.json` like me - [here's the short cautionary tale](/2026/01/31/when-opencode-cant-see-your-docs/) on why that matters.
52+
5153 The migration took a few prompts and reviews, but the payoff is immediate. Sometimes the research is right: AGENTS.md with targeted docs really does work better than monolithic skills.
5254
5355 _[EDIT]: Token usage is way down._
_posts/2026-01-31-when-opencode-cant-see-your-docs.md+46−0
@@ -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.
_site/about/index.html+1−1
@@ -69,7 +69,7 @@ These are my random thoughts, notes, and cries to the edge.</p>
6969 <div class="ascii-line">+--------------------------------------------------------------------------+</div>
7070 </main>
7171 <footer class="site-footer">
72- <span class="prompt">$</span> last build 2026-01-30
72+ <span class="prompt">$</span> last build 2026-01-31
7373 </footer>
7474 </div>
7575 <script src="/assets/js/galaxy.js"></script>
_site/index.html+11−1
@@ -50,11 +50,21 @@
5050
5151 <ul class="post-list">
5252
53+ <li>
54+ <span class="post-date">2026-01-31</span>
55+ <a href="/posts/when-opencode-cant-see-your-docs/">cautionary tale about the agents.md migration</a>
56+ </li>
57+
5358 <li>
5459 <span class="post-date">2026-01-31</span>
5560 <a href="/posts/ditching-skills-for-agents-md/">agents.md migration</a>
5661 </li>
5762
63+ <li>
64+ <span class="post-date">2026-01-31</span>
65+ <a href="/posts/blond-hound-games/">Blond Hound Games</a>
66+ </li>
67+
5868 <li>
5969 <span class="post-date">2026-01-30</span>
6070 <a href="/posts/rpg-project-started/">rpg project started</a>
@@ -76,7 +86,7 @@
7686 <div class="ascii-line">+--------------------------------------------------------------------------+</div>
7787 </main>
7888 <footer class="site-footer">
79- <span class="prompt">$</span> last build 2026-01-30
89+ <span class="prompt">$</span> last build 2026-01-31
8090 </footer>
8191 </div>
8292 <script src="/assets/js/galaxy.js"></script>
_site/posts/hello-world/index.html+1−1
@@ -60,7 +60,7 @@
6060 <div class="ascii-line">+--------------------------------------------------------------------------+</div>
6161 </main>
6262 <footer class="site-footer">
63- <span class="prompt">$</span> last build 2026-01-30
63+ <span class="prompt">$</span> last build 2026-01-31
6464 </footer>
6565 </div>
6666 <script src="/assets/js/galaxy.js"></script>
_site/posts/opencode-setup/index.html+3−1
@@ -65,6 +65,8 @@
6565
6666 <p><strong>The Blog Writer Agent</strong> (which is writing this post) specializes in personal, informal content. It researches topics, structures posts with hooks and takeaways, and always includes sources. Temperature is cranked up to 0.7 for creativity.</p>
6767
68+<p>Model choice is simple, the Debug and Plan agents use Claude Opus, and the Build mode I switch between Codex and Gemini. This keeps token usage and costs down, while still using good coding models for hard tasks.</p>
69+
6870 <h2 id="quick-commands-for-common-tasks">Quick Commands for Common Tasks</h2>
6971
7072 <p>I’ve got three slash commands that handle the boring stuff:</p>
@@ -100,7 +102,7 @@
100102 <div class="ascii-line">+--------------------------------------------------------------------------+</div>
101103 </main>
102104 <footer class="site-footer">
103- <span class="prompt">$</span> last build 2026-01-30
105+ <span class="prompt">$</span> last build 2026-01-31
104106 </footer>
105107 </div>
106108 <script src="/assets/js/galaxy.js"></script>
_site/sitemap.xml+8−0
@@ -13,10 +13,18 @@
1313 <lastmod>2026-01-30T00:00:00-06:00</lastmod>
1414 </url>
1515 <url>
16+<loc>http://0.0.0.0:4000/posts/blond-hound-games/</loc>
17+<lastmod>2026-01-31T00:00:00-06:00</lastmod>
18+</url>
19+<url>
1620 <loc>http://0.0.0.0:4000/posts/ditching-skills-for-agents-md/</loc>
1721 <lastmod>2026-01-31T00:00:00-06:00</lastmod>
1822 </url>
1923 <url>
24+<loc>http://0.0.0.0:4000/posts/when-opencode-cant-see-your-docs/</loc>
25+<lastmod>2026-01-31T00:00:00-06:00</lastmod>
26+</url>
27+<url>
2028 <loc>http://0.0.0.0:4000/about/</loc>
2129 </url>
2230 <url>
cautionary-tale.md+35−0
@@ -0,0 +1,35 @@
1+When OpenCode Can’t See Your Docs
2+
3+I just spent 20 minutes watching Claude flail around like a lost tourist.
4+
5+The Setup
6+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.
7+Then I fired up OpenCode and asked Claude to help with a bug.
8+
9+The Confusion
10+“Read the systematic debugging guide first,” I said, pointing at the file path.
11+Claude squinted at the screen. “I don’t see that file. Let me search for debugging patterns instead…”
12+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.
13+I tried again. “It’s in `.agent-docs/debugging/01-overview-iron-law.md`.”
14+More confusion. Claude could see the current directory files just fine, but anything in my docs folder might as well have been on Mars.
15+
16+The Lightbulb
17+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.
18+Five minutes later, I created `opencode.json`:
19+
20+```json
21+{
22+ "instructions": [
23+ ".agent-docs/**/*.md",
24+ ".agent-docs/**/*.ts",
25+ ".agent-docs/**/*.sh"
26+ ]
27+}
28+```
29+
30+The Relief
31+Restarted OpenCode. Asked the same question.
32+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.
33+
34+The Takeaway
35+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.