3 ms·
From the article: > We recommend keeping task-specific instructions in separate markdown files with self-descriptive names somewhere in your project. Then, in
by vunderba 11mo ago
From the article:
> We recommend keeping task-specific instructions in separate markdown files with self-descriptive names somewhere in your project. Then, in your CLAUDE.md file, you can include a list of these files with a brief description of each, and instruct Claude to decide which (if any) are relevant and to read them before it starts working.
I've been doing this since the early days of agentic coding though I've always personally referred to it as the Table-of-Contents approach to keep the context window relatively streamlined. Here's a snippet of my CLAUDE.md file that demonstrates this approach:
# Documentation References
- When adding CSS, refer to: docs/ADDING_CSS.md
- When adding assets, refer to: docs/ADDING_ASSETS.md
- When working with user data, refer to: docs/STORAGE_MANAGER.md
Full CLAUDE.md file for reference:
https://gist.github.com/scpedicini/179626cfb022452bb39eff10becb95fa https://gist.github.com/scpedicini/179626cfb022452bb39eff10b...
- sothatsit 11mo agoI have also done this, but my results are very hit or miss. Claude rarely actually reads the other documentation files I point it to.
- dhorthy 11mo agoI think the key here is “if X then Y syntax” - this seems to be quite effective at piercing through the “probably ignore this” system message by highlighting WHEN a given instruction is “highly relevant”
- throwaway314155 11mo agoWhat?
- xpe 11mo agoIt helps when questions intended to resolve ambiguity are not themselves hopelessly ambiguous. See also: "Help me help you" - https://en.wikipedia.org/wiki/Jerry_Maguire https://en.wikipedia.org/wiki/Jerry_Maguire
- Sammi 11mo agoYeah I don't trust any agent to follow document references consistently. I just manually add the relevant files to context every single time. Though I know some people who have built an mcp that does exactly this: https://www.usable.dev/ https://www.usable.dev/ It's basically a chat-bot frontend to your markdown files, with both rag and graph db indexes.
- wry_discontent 11mo agoThat makes sense given that it's trained on real world developers.
- dimitri-vs 11mo agoCorrect me if I'm wrong but I think the new "skillss are exactly this, but better.
- vunderba 11mo agoYeah I think "Skills" are just a more codified folder based approach to this TOC system. The main reason I haven't migrated yet is that the TOC approach lends itself better to the more generic AGENTS.md style - allowing me to swap over to alternative LLMs (such as Gemini) relatively easily.
- stpedgwdgfhgdd 11mo agoIndeed, the article links to the skill documentation which says: Skills are modular capabilities that extend Claude’s functionality through organized folders containing instructions, scripts, and resources. And Extend Claude’s capabilities for your specific workflows E.g. building your project is definitely a workflow. It als makes sense to put as much as you can into a skill as this an optimized mechanism for claude code to retrieve relevant information based on the skill’s frontmatter.
- Zarathruster 11mo agoI've done this too. The nice side-benefit of this approach is that it also serves as good documentation for other humans (including your future self) when trying to wrap their heads around what was done and why. In general I find it helpful to write docs that help both humans and agents to understand the structure and purpose of my codebase.