If you have worked with AI coding agents for any meaningful period, you have probably hit this wall: the agent knows things that are documented somewhere in your project, but it cannot find them when it needs them. It reads the wrong file. It misses a convention. It reinvents something that already exists three directories away.
I have been fighting this exact problem, and the solution turned out to be deceptively simple: give your agent a table of contents.
The First File Matters Most
In Agentic Engineering, the entry point — the first file the agent reads when it enters a project — is the highest-leverage file you will ever write. In the Claude Code ecosystem, that file is CLAUDE.md. OpenAI’s equivalent is AGENTS.md. Regardless of the name, the principle is the same.
Think of it as the receptionist at a large office — it does not need to know everything, but it needs to know exactly where everything is and who to talk to.
Here is the critical insight from both OpenAI’s Harness Engineering research and Anthropic’s own guidance: the entry point file works best as a ~100-line pointer document, not a comprehensive knowledge dump.
HumanLayer’s community research confirmed it — ideally under 300 lines, best under 100. The reason is straightforward: as instruction count increases, the agent’s compliance with all instructions degrades uniformly. Not just the new ones. All of them.
What Goes Into 108 Lines?
My CLAUDE.md is exactly 108 lines. Here is what fits:
Architecture Vision (5 sentences): What the system does and why certain quality attributes matter more than others. This is the “north star” the agent refers back to when making judgment calls.
Quick Reference Table: App name, purpose, tech stack, repo structure — the facts an agent needs in the first 10 seconds.
Commands Table (14 commands): Every command the agent might need to run. Install, test, lint, typecheck, database operations, verification. No explanations — just the command and its purpose.
Architecture Summary (7 layers): The layering rule in one line, followed by each layer’s responsibilities and import rules. This is the single most referenced section during implementation.
Golden Principles (7 rules): Non-negotiable constraints. “No fabrication.” “Repository layer owns all I/O.” “Structured logging only.” These connect directly to the product guardrails I describe in Part 9 and the traceability chains in Part 5.
Architectural Heuristics (3 heuristics): Decision-making rules with correct/incorrect examples. “Prefer local knowledge over web research.” “Fail loudly, recover gracefully.”
Boundaries (3 boundaries): Preconditions for dangerous operations. No schema changes without updating Pydantic models. No new dependencies without checking references.
Documentation Map (25 rows): The actual table of contents — every document, its path, and its purpose.
Progressive disclosure: the lean entry point fans out to detailed documents only when needed.
The “Pointer, Not Content” Principle
This is perhaps the most important Agentic Engineering principle in this entire series: the entry point should contain pointers, not content.
Instead of explaining how session management works inside CLAUDE.md, it points to the relevant documents:
| Architecture | ARCHITECTURE.md | System decomposition, domains, layering |
| Design Docs | docs/design-docs/dd-*.md | Technical decisions |
| Product Specs | docs/product-specs/*.md | Feature specifications |
| References | docs/references/*.md | Library-specific guides |When the agent needs to work on session management, it reads the pointer in CLAUDE.md, navigates to the relevant design doc and product spec, and gets the full context. CLAUDE.md stays lean, and the agent gets exactly the depth it needs for the task at hand.
Anthropic calls this progressive disclosure. The agent gets a high-level map first, then drills into the specific documents relevant to its current task. This is why the 44-document knowledge store from Part 2 works — the entry point is lean, but the depth is always available one click away.
The Instruction Density Trap
Here is the part that surprised me during my research. It is not about line count — it is about instruction density. A 100-line file with 50 distinct directives is denser than a 100-line file with 15 directives and lots of context.
My 108-line CLAUDE.md contains approximately 40-50 distinct directives. That is within the safe range, but approaching the zone where adding more instructions starts degrading compliance with existing ones. The research suggests frontier models handle ~150-200 instructions reasonably; after that, degradation becomes measurable.
The practical implication: every time I want to add a new rule to CLAUDE.md, I first ask whether an existing rule can be consolidated or moved to a downstream document. The entry point must stay lean.
Results in Practice
After implementing this pattern, the agent’s behavior changed noticeably:
- Convention compliance: The agent follows naming conventions, layering rules, and import restrictions without being reminded mid-session
- Document navigation: Instead of searching randomly, the agent checks the documentation map and goes directly to the relevant file
- Consistency: Because every session starts by reading the same 108-line foundation, behavior is reproducible across sessions
The most telling metric: across all 44 generated documents in the knowledge store, the verification pass found 0 terminology inconsistencies. That consistency traces directly back to the golden principles and architecture summary in CLAUDE.md being read before every generation step.
How This Connects to the Series
The entry point is the foundation that makes every other Agentic Engineering pattern possible:
- The role-based personas from Part 3 all begin by reading CLAUDE.md, which gives them shared vocabulary
- The traceability chains from Part 5 are anchored in the golden principles defined here
- The product guardrails from Part 9 translate the architecture vision into measurable thresholds
Without a well-structured entry point, none of these patterns can be reliably applied. The entry point is not just a file — it is the contract between you and your agent.
One Thing I Would Improve
The documentation map at the bottom of CLAUDE.md takes up ~25 lines. That is a lot of real estate for what is essentially an index. I am considering moving it to a separate docs/INDEX.md and replacing it with a single pointer line in CLAUDE.md. That would free up space for more actionable instructions without increasing instruction density.
If you are working with AI coding agents, try this: create a lean entry point file that acts as a table of contents. Keep it under 100-150 lines. Use pointers, not content. And audit it regularly for instruction density — because the file your agent reads first is the file that shapes everything that follows.
What has your experience been with structuring agent knowledge? I would love to hear how others are solving this problem.