𝗧𝘄𝗼 𝗟𝗮𝘆𝗲𝗿 𝗗𝗼𝗰𝘂𝗺𝗲𝗻𝘁𝗮𝘁𝗶𝗼𝗻 𝗳𝗼𝗿 𝗔𝗜 𝗔𝗴𝗲𝗻𝘁𝘀

𝗧𝘄𝗼 𝗟𝗮𝘆𝗲𝗿 𝗗𝗼𝗰𝘂𝗺𝗲𝗻𝘁𝗮𝘁𝗶𝗼𝗻 𝗳𝗼𝗿 𝗔𝗜 𝗔𝗴𝗲𝗻𝘁𝘀

AI agents start every session with zero context. They do not know your architecture or naming rules.

Many people dump all documentation into the prompt. This ruins performance. Models lose information in the middle of long contexts.

Use a two layer system instead.

Layer 1: CLAUDE.md

• Keep it under 300 lines.
• It loads every session.
• It acts as a routing table.

Layer 2: agent_docs folder

• Store deep details here.
• The agent reads these files on demand.
• It only pulls information needed for the task.

Write your routing table with task triggers.

• Do not describe the content.
• Describe the task.
• Use words you use when assigning work.

Bad trigger: Project architecture overview. Good trigger: Orienting in the codebase.

This pattern stops bugs. A case study showed it prevents crashes and missing registrations. It ensures the agent follows your project conventions.

Keep your docs healthy.

• Use pointers to specific code lines.
• Do not copy code into docs.
• Update docs in the same PR as your code.

Source: https://dev.to/demandt/a-two-layer-documentation-pattern-for-ai-coding-agents-4k32 Optional learning community: https://t.me/GyaanSetuAi