This is a very long post, i am sorry about that. MD files are useful for giving agents certain capabilities, but we have a problem: Agents, for example CC reads the claude.md file at session start and adds it to context, but this does not mean every command we give there will work 100%. Or in some places we have commands in md files where we say when they should run, but we struggle to define that timing. I have a scenario where I overcame this problem; I will explain with an example: As the project I developed with agents grows, due to the context-memory problem I keep a file called structure.json. In this file I store information such as the module, dependencies and functions. If I need to give a snippet, it looks like this: “main/pluginsManager”: { “file”: “src/main/pluginsManager.js”, “description”: “Plugins Manager Module”, “exports”: [ “init”, “setupIPC”, “getAllPlugins”, “togglePlugin” ], “depends”: [ “fs”, “path”, “os”, “child_process”, “shared/ipcChannels” ], “functions”: { “init”: { “line”: 24, “params”: [ “window” ], “purpose”: “Initialize plugins manager” }, “readJsonFile”: { “line”: 31, “params”: [ “filePath” ], “purpose”: “Read JSON file safely” … and it continues like this. Every time we make a new development I need to update this file but I don’t want to tell this with a prompt every time. Because of the problem I mentioned at the beginning I also cannot do it by putting commands into the md file because I cannot be sure it will work 100%. And we need to think about this, when can we be sure what we need to do is done? The agent says it’s done → not necessarily The code compiles → may still be wrong Tests pass → behavior can still drift However one action is deterministic: commit. We cannot call this the absolute final result either but this is the closest moment to 100%. And it is a very clearly triggerable action. So I update my structure file on every commit. If your project is large or has growth potential, I strongly recommend developing with disciplined and regular commits using git to preserve context. By doing this I managed to build my structure.json file regularly. But other problems emerged, first the file becomes very large as the project grows. For this I do indexing. But again the problem I mentioned at the beginning appears, since I write it in the md file at every session start the agent reads structure.json every time. But later when I give a task, while searching files the agent still does not behave deterministically. For this I developed the following solution: Smarter Module Navigation: intentIndex & find-module CLI Tool intentIndex -> The structure update script now auto-groups modules by feature. 40 modules become 22 searchable features. Generated on every commit, zero maintenance. For example : find-module CLI tool — Instead of reading 3,690 lines, agents run a single command: $ node scripts/find-module.js github Feature: github src/main/githubManager.js — GitHub Manager Module src/renderer/githubPanel.js — GitHub Panel Module IPC: LOAD_GITHUB_ISSUES, OPEN_GITHUB_ISSUE, TOGGLE_GITHUB_PANEL Three-layer search: exact match in intentIndex → partial match in module names → deep search in descriptions, exports, and IPC channels. Key Insight : Adding an index inside a large JSON file isn’t enough — agents naturally default to grep/glob when searching. The fix was meeting the agent where it already works: the terminal. A CLI tool that returns 5 lines beats an index buried in 3,690 lines. AGENTS.md now instructs agents to run find-module before manual searches. Nothing in the existing system changed — session-start reading, pre-commit hook, module parsing all work exactly as before. Over time I realized the core issue wasn’t documentation quality, it was the control model. We keep treating agents like instruction-following programs, but they behave more like event-driven systems. Prompts describe intent, yet behavior is ultimately shaped by the environment they operate in. Markdown files are advisory, not authoritative; they compete with search heuristics, planning steps, and token pressure. But events — like a commit — are different. An event is an explicit boundary acknowledged by both the human and the system. This also explains why CLI tools worked better than carefully written docs. Agents are trained around interactive tooling workflows, so querying a system aligns with how they “expect” to operate, while reading large documentation does not. The moment architecture becomes queryable instead of descriptive, the agent stops interpreting and starts executing. The reliability didn’t come from better instructions — it came from turning guidance into contracts and actions into lifecycle events. In practice the pattern became clear: prompts are suggestions documentation is reference events are guarantees tools are contracts I also shared this before, I developed a terminal-focused lightweight ide for projects I develop with CC. My goal was to keep context, standardize my projects and be more organized. I achieved these but while building and using it I encountered the problems I mentioned. I solved some of them this way. If you have similar examples or approaches you know I would like to hear and learn. If you want to check it out my project is open source, you can access it here: Github: https://github.com/kaanozhan/Frame submitted by /u/Direct_Librarian9737
Originally posted by u/Direct_Librarian9737 on r/ClaudeCode