{"slug": "a-repo-local-markdown-documentation-system-that-helps-humans-and-ai-agents-a-the", "title": "A repo-local Markdown documentation system that helps humans and AI agents understand a codebase, find the right context, and make safer changes. Ask your agent to help you set it up.", "summary": "A developer created a repo-local Markdown documentation system designed to help both humans and AI agents understand a codebase, find relevant context, and make safer changes. The system uses a top-level AGENTS.md as an index and a docs/ folder with structured documentation for systems, flows, architecture, and glossary terms. It aims to keep documentation close to the code and require updates alongside code changes.", "body_md": "[Summary](https://gist.github.com/starred.atom#summary)[Goals](https://gist.github.com/starred.atom#goals)[Repository Structure](https://gist.github.com/starred.atom#repository-structure)`AGENTS.md`\n\n[Documentation Types](https://gist.github.com/starred.atom#documentation-types)[Documentation Templates](https://gist.github.com/starred.atom#documentation-templates)[Documentation Style](https://gist.github.com/starred.atom#documentation-style)[Documentation Granularity](https://gist.github.com/starred.atom#documentation-granularity)[Source Maps](https://gist.github.com/starred.atom#source-maps)[Code Comments](https://gist.github.com/starred.atom#code-comments)[Keeping Docs Updated](https://gist.github.com/starred.atom#keeping-docs-updated)[Agent Workflow](https://gist.github.com/starred.atom#agent-workflow)[Initial Implementation Guidance](https://gist.github.com/starred.atom#initial-implementation-guidance)[Viewing Documentation with MDTS](https://gist.github.com/starred.atom#viewing-documentation-with-mdts)[Extending the Documentation System](https://gist.github.com/starred.atom#extending-the-documentation-system)\n\nThis documentation system exists because humans and AI agents are only as reliable as the context they can find. Without durable repo-local documentation, contributors have to infer product behavior, system boundaries, domain terms, and architectural constraints from scattered source files, comments, issues, and one-off instructions. That makes changes slower and increases the chance of breaking assumptions that were only implicit.\n\nThis document describes a lightweight, repo-local documentation system that functions as a shared knowledge base for humans and AI coding agents. `AGENTS.md`\n\nis the routing layer. The `docs/`\n\nfolder contains durable documentation for systems, flows, architecture, glossary terms, and templates.\n\nThe source code remains the implementation source of truth. Documentation explains the system at a useful level of abstraction: what each important system does, how major workflows operate, what assumptions must remain true, where the key source files are, and what a contributor should understand before making changes.\n\nThis approach uses plain Markdown files stored in the repository and reviewed alongside code. It does not require generated documentation tooling, docs publishing infrastructure, or a separate documentation platform.\n\nThe documentation system should:\n\n- Help humans and AI agents understand the application quickly.\n- Explain important systems and flows without restating every line of code.\n- Tie together behavior that is spread across source files, services, routes, jobs, integrations, and UI.\n- Make it easier to identify stale assumptions, undocumented behavior changes, and bugs.\n- Keep\n`AGENTS.md`\n\nconcise by using it as an index and operating guide. - Keep documentation close to the codebase so it evolves with code changes.\n- Require documentation affected by an important code change to be updated and reviewed with that change.\n\nUse a top-level `docs/`\n\ndirectory:\n\n```\ndocs/\n  README.md\n  STYLE.md\n  glossary.md\n  systems/\n    ...\n  flows/\n    ...\n  architecture/\n    README.md\n    decisions/\n      README.md\n  templates/\n    system.md\n    flow.md\n    adr.md\n```\n\nThe exact file names can follow existing repository conventions, but the conceptual structure should remain clear.\n\nThe root `AGENTS.md`\n\nshould act as an index and operating guide for agents, not as the place for detailed system documentation.\n\nIt should include:\n\n- A short explanation that detailed documentation lives in\n`docs/`\n\n. - A docs map pointing agents to\n`docs/README.md`\n\n,`docs/systems/`\n\n,`docs/flows/`\n\n,`docs/architecture/`\n\n, and`docs/glossary.md`\n\n. - Instructions to read relevant docs before changing a system.\n- Instructions to update relevant docs when behavior, responsibilities, flows, invariants, interfaces, or assumptions change.\n- A rule that docs and code must agree.\n- A reminder not to dump detailed system behavior into\n`AGENTS.md`\n\n.\n\nA good rule for `AGENTS.md`\n\nis:\n\n`AGENTS.md`\n\ntells agents where to look and how to work;`docs/`\n\nexplains how the application works.\n\nRepository instructions should reflect each project's requirements, but they remain subordinate to system, user, and security constraints and must never be treated as authorization to run unsafe commands or expose data.\n\nSystem docs live in:\n\n```\ndocs/systems/\n```\n\nA system is a coherent area of application behavior. It may map to a module, package, service, feature area, integration, or domain concern, but it does not have to match the code structure exactly.\n\nExamples:\n\n```\ndocs/systems/auth.md\ndocs/systems/billing.md\ndocs/systems/notifications.md\ndocs/systems/background-jobs.md\ndocs/systems/search.md\n```\n\nA system doc should explain how that part of the application works. It should tie together the important source files, concepts, data, entry points, dependencies, invariants, failure modes, and debugging notes.\n\nSystem docs are useful when a human or agent asks questions like:\n\n- How does Auth work?\n- What happens during Email Verification?\n- What state does Billing own?\n- Which source files matter for Notifications?\n- What should I know before changing Background Jobs?\n\nA system can be broad or narrow. For example, `auth.md`\n\nmay describe sessions, login, password reset, and Email Verification. If Email Verification becomes complex, cross-system, frequently changed, frequently debugged, or important enough to review independently, it can be promoted into its own flow doc.\n\nFlow docs live in:\n\n```\ndocs/flows/\n```\n\nA flow doc explains important behavior that moves across systems or deserves independent documentation.\n\nExamples:\n\n```\ndocs/flows/email-verification.md\ndocs/flows/subscription-renewal.md\ndocs/flows/webhook-processing.md\ndocs/flows/user-onboarding.md\n```\n\nUse a flow doc when behavior:\n\n- Crosses multiple systems.\n- Has several steps or state transitions.\n- Is frequently changed or debugged.\n- Involves external services.\n- Has important error handling.\n- Has security, billing, data integrity, or user-visible implications.\n\nFlow docs should describe triggers, participants, steps, state changes, failure behavior, observability, testing, and source files.\n\nArchitecture docs live in:\n\n```\ndocs/architecture/\n```\n\nThe architecture directory is for cross-system architecture, durable technical decisions, and system-wide constraints. It should explain why the application is shaped a certain way when that explanation affects more than one system.\n\nArchitecture docs are different from system and flow docs:\n\n`docs/systems/`\n\nexplains how a specific system currently works.`docs/flows/`\n\nexplains important behavior that moves across systems.`docs/architecture/`\n\nexplains broader structure, long-lived constraints, and architectural decisions.\n\nUse `docs/architecture/`\n\nfor topics such as:\n\n- System-wide patterns.\n- Durable technical constraints.\n- Cross-system boundaries.\n- Major integration strategies.\n- Persistence or deployment assumptions.\n- Architectural tradeoffs.\n- Architecture Decision Records.\n\nDo not use `docs/architecture/`\n\nfor ordinary implementation notes, feature documentation, or detailed behavior that belongs in a system or flow document.\n\nArchitecture Decision Records, or ADRs, live in:\n\n```\ndocs/architecture/decisions/\n```\n\nADRs document proposed, active, and historical technical decisions, including their context, tradeoffs, consequences, and rejected alternatives.\n\nADRs in `docs/architecture/decisions/`\n\ndescribe architectural decisions considered for the codebase. Agents and humans should treat only ADRs with an `Accepted`\n\nstatus as current guidance when reviewing, planning, or changing code.\n\nArchitectural decisions are human-owned. Agents can help draft ADR text from accepted decisions and keep existing ADRs aligned with code.\n\nUse ADRs for decisions that shape the system beyond a single implementation detail, such as:\n\n- Why authentication is session-based instead of token-only.\n- Why billing webhooks are processed asynchronously.\n- Why a specific database owns a specific kind of state.\n- Why background jobs must be idempotent.\n- Why a third-party integration is isolated behind an adapter.\n\nProposed architectural decisions should be discussed in PRs, issues, planning docs, or review comments. An ADR may be created while that discussion is in progress with a `Proposed`\n\nstatus, then changed to `Accepted`\n\nonce the decision is approved.\n\nDo not rewrite an accepted ADR to describe a different decision. When a decision changes, create a new ADR, mark the old ADR as `Superseded`\n\n, and link the old ADR to its replacement with `superseded_by`\n\n. Accepted ADRs may still receive small corrections or links that do not change the recorded decision.\n\nEvery ADR must begin with YAML frontmatter. The allowed fields are:\n\n`status`\n\n(required): one of`Proposed`\n\n,`Accepted`\n\n,`Superseded`\n\n,`Deprecated`\n\n, or`Rejected`\n\n.`date`\n\n(required): the date the ADR was created, formatted as`YYYY-MM-DD`\n\n.`superseded_by`\n\n(required only for`Superseded`\n\nADRs): a repository-relative path to the replacement ADR.\n\nDo not add other frontmatter fields unless the project deliberately extends this schema in its documentation style guide. The statuses mean:\n\n`Proposed`\n\n: under discussion and not current guidance.`Accepted`\n\n: the current decision.`Superseded`\n\n: replaced by a newer ADR.`Deprecated`\n\n: discouraged but still relevant historically.`Rejected`\n\n: considered but intentionally not adopted.\n\nRoutine implementation details, small refactors, bug fixes, and temporary workarounds belong in code, PRs, issues, or ordinary documentation instead of ADRs.\n\nThe glossary lives at:\n\n```\ndocs/glossary.md\n```\n\nThe glossary defines important domain terms used across the application. It helps humans and agents avoid making incorrect assumptions about words that have specific meaning in the product or codebase.\n\nExamples of useful glossary terms:\n\n- Account\n- Workspace\n- Member\n- Organization\n- Session\n- Subscription\n- Email Verification\n- Verification Token\n\nGlossary entries should use Title Case for their headings.\n\nIn finished documentation, prefer using the same Title Case form when referring to glossary-defined concepts, especially when it improves clarity or distinguishes an application-specific concept from an ordinary word.\n\nTreat Title Case as a clarity aid for finished docs. A glossary concept can still appear in lowercase in drafts, comments, source code identifiers, issues, or informal notes.\n\nTemplates live in:\n\n```\ndocs/templates/\n```\n\nTemplates keep documentation consistent and make it easier for humans and agents to create new docs.\n\nRecommended templates:\n\n```\ndocs/templates/system.md\ndocs/templates/flow.md\ndocs/templates/adr.md\n```\n\nA system doc should generally use this structure:\n\n```\n# <System Name>\n\n## Purpose\n\nExplain what this system does and why it exists.\n\n## Questions this doc answers\n\nList the practical questions this document is meant to answer.\n\n## Scope\n\nDescribe what is included in this system.\n\n## Non-scope\n\nDescribe what this system does not own, especially where boundaries are easy to misunderstand.\n\n## Key concepts\n\nDefine important domain concepts, states, entities, and terms used by this system.\n\nUse Title Case for concepts that are defined in `docs/glossary.md` when doing so improves clarity.\n\n## How the system works\n\nExplain the system at a behavioral level. Focus on important mechanics, responsibilities, and interactions. Do not restate every implementation detail.\n\n## Important flows\n\nDescribe major flows handled by this system. Link to separate flow docs when a flow is large, cross-system, frequently changed, frequently debugged, or important enough to review independently.\n\n## Data and state\n\nDescribe important persisted data, in-memory state, caches, queues, external state, or derived state used by this system.\n\n## Interfaces and entry points\n\nList the main ways this system is used, such as API routes, UI entry points, background jobs, event handlers, webhooks, services, public functions, or external integrations.\n\n## Dependencies\n\nList systems, services, packages, APIs, or infrastructure this system depends on.\n\n## Downstream effects\n\nDescribe what other systems may be affected when this system changes.\n\n## Invariants and assumptions\n\nList rules that must remain true for the system to behave correctly.\n\n## Error handling\n\nDescribe important failure modes and how the system handles them.\n\n## Security and privacy notes\n\nDocument security-sensitive behavior, permissions, authentication, authorization, user data handling, and privacy assumptions. Omit only if clearly irrelevant.\n\n## Observability and debugging\n\nExplain how to debug this system. Include relevant logs, metrics, traces, dashboards, admin screens, commands, or common symptoms when applicable.\n\n## Testing notes\n\nDescribe important tests and how to validate changes.\n\n## Common pitfalls\n\nList things contributors or agents are likely to misunderstand.\n\n## Source map\n\nLink to the most important source files. Do not list every file unless the system is small.\n\n## Related docs\n\nLink to related system docs, flow docs, ADRs, glossary entries, or external references.\n```\n\nA flow doc should generally use this structure:\n\n```\n# <Flow Name>\n\n## Purpose\n\nExplain what this flow accomplishes and why it matters.\n\n## Trigger\n\nDescribe what starts the flow.\n\n## Participants\n\nList the systems, services, users, jobs, routes, integrations, or external providers involved.\n\n## Step-by-step flow\n\nDescribe the main sequence of behavior.\n\n## Data and state changes\n\nDescribe important data created, updated, deleted, cached, queued, or derived during the flow.\n\n## Success behavior\n\nDescribe what is true when the flow succeeds.\n\n## Failure behavior\n\nDescribe important failure modes, retries, fallbacks, compensating behavior, and user-visible errors.\n\n## External dependencies\n\nList external services, APIs, providers, infrastructure, or configuration required by this flow.\n\n## Invariants and assumptions\n\nList rules that must remain true for this flow to behave correctly.\n\n## Security and privacy notes\n\nDocument security-sensitive behavior, permissions, authentication, authorization, user data handling, and privacy assumptions. Omit only if clearly irrelevant.\n\n## Observability and debugging\n\nExplain how to debug this flow. Include logs, metrics, traces, dashboards, admin screens, commands, or common symptoms when applicable.\n\n## Testing notes\n\nDescribe important tests and how to validate changes.\n\n## Source map\n\nLink to the most important source files.\n\n## Related docs\n\nLink to related system docs, flow docs, ADRs, glossary entries, or external references.\n```\n\nThe ADR template should generally use this structure:\n\n```\n---\nstatus: Proposed\ndate: \"YYYY-MM-DD\"\n---\n\n# <Decision Title>\n\n## Context\n\nDescribe the problem, forces, constraints, and relevant background.\n\n## Decision\n\nDescribe the decision that was made.\n\n## Consequences\n\nDescribe the expected benefits, costs, risks, and tradeoffs.\n\n## Alternatives considered\n\nList meaningful alternatives and why they were not chosen.\n\n## Related code\n\nLink to important source files affected by this decision.\n\n## Related docs\n\nLink to related system docs, flow docs, ADRs, glossary entries, or external references.\n```\n\nAll new ADRs should follow the ADR template unless there is a clear reason to extend it.\n\nDocumentation should be written for both humans and AI agents.\n\nGood documentation should:\n\n- Use clear, direct Markdown.\n- Prefer stable headings.\n- Link to related docs and source files with Markdown relative links from the current file.\n- Explain behavior, responsibilities, flows, invariants, and pitfalls.\n- Avoid restating every implementation detail.\n- Avoid unsupported guesses.\n- Mark uncertainty explicitly when behavior is hard to infer.\n- Include source maps for important files.\n- Stay concise enough to read before making changes.\n\nThe best docs are not exhaustive. They are navigational and explanatory. They help a reader understand what matters, where the details live, and what could break if the system changes.\n\nCreate or expand documentation when behavior is important enough that a human or agent would otherwise need to inspect several files to understand it.\n\nKeep documentation inside a system doc when the behavior is local and easy to explain there.\n\nCreate a separate flow doc when the behavior:\n\n- Crosses multiple systems.\n- Has several steps or states.\n- Is frequently changed or debugged.\n- Has important error handling.\n- Involves external services.\n- Has security, billing, data integrity, or user-visible implications.\n\nDo not document every file. Prioritize systems and flows that are central, risky, frequently changed, difficult to infer, or important to user-visible behavior.\n\nEvery system and flow doc should include a source map linking to the most important files that implement the behavior.\n\nA source map should help the reader inspect details without forcing them to rediscover where the implementation lives.\n\nDo not list every file unless the system or flow is small. Prefer the most important entry points, state definitions, handlers, services, jobs, tests, and integration files.\n\nUse code comments for implementation-specific context that is most useful when read directly beside the code. Agents should read relevant docs first, then use comments as local context while inspecting source files.\n\nGood comments explain non-obvious behavior, ordering constraints, side effects, invariants, security assumptions, external API quirks, retries, caching behavior, concurrency concerns, or cases where a local implementation affects another system.\n\nPrefer comments when they prevent a real misunderstanding, bug, unsafe refactor, or unnecessary rediscovery.\n\nGood uses for code comments include:\n\n- Explaining why a non-obvious branch exists.\n- Explaining why operations must happen in a specific order.\n- Explaining why a variable, flag, or state transition triggers behavior in another system.\n- Explaining why a retry, debounce, cache invalidation, lock, or transaction is necessary.\n- Explaining why a security check exists.\n- Explaining why an external API is called in an unusual way.\n- Explaining what invariant a block of code preserves.\n- Explaining what edge case or failure mode the code protects against.\n\nAvoid comments that:\n\n- Restate what the code already says.\n- Explain obvious variable names.\n- Duplicate system documentation.\n- Add long architectural explanations inside source files.\n- Leave stale historical notes that belong in an ADR.\n\nUse system docs to explain how a system works. Use flow docs to explain cross-system behavior. Use code comments to explain why a specific implementation detail exists.\n\nDocumentation must be updated when code changes affect important system understanding.\n\nEvery pull request that changes behavior, interfaces, security, data, or operational procedures must update the affected documentation as part of the same change. Reviewers should treat documentation as part of the code change and verify that it is accurate before approving the work.\n\nUpdate relevant docs when a change affects:\n\n- System responsibilities.\n- Runtime behavior.\n- User-visible behavior.\n- Internal workflows.\n- Data models or persistence behavior.\n- External integrations.\n- Public APIs.\n- Configuration.\n- Error handling.\n- Security or auth behavior.\n- Important invariants or assumptions.\n- Testing or debugging expectations.\n- Glossary-defined domain concepts.\n\nDocumentation is valid only when it accurately describes the intended behavior of the current code.\n\nIf docs and code disagree, contributors must do one of the following:\n\n- Update the docs to match the code.\n- Update the code to match the documented intent.\n- Explicitly call out the mismatch for review.\n\nThis makes documentation useful during code review. Reviewers can compare docs and code to catch stale assumptions, missing behavior changes, or bugs caused by mismatched intent and implementation.\n\nWhen an AI coding agent works in the repository, it should follow this workflow:\n\n- Read\n`AGENTS.md`\n\n. - Use\n`docs/README.md`\n\nto find relevant documentation. - Read the system, flow, architecture, and glossary docs related to the area being changed.\n- Inspect source files for implementation details.\n- Make the code change.\n- Update relevant docs if behavior, responsibilities, flows, invariants, assumptions, interfaces, or glossary-defined concepts changed.\n- Ensure docs and code agree before finishing.\n\nThis gives agents enough context to work effectively without requiring every task to start with full-codebase exploration.\n\nWhen introducing this system to an existing codebase, do not try to document everything at once.\n\nStart with the most important systems and flows, such as:\n\n- Core domain systems.\n- Auth, session, and user systems.\n- API/server behavior.\n- Data access and persistence.\n- Background jobs or workers.\n- External integrations.\n- Billing, payments, or subscriptions, if present.\n- Notifications, email, or webhooks, if present.\n- Important UI or application flows.\n\nEach initial doc should be accurate, useful, and linked to relevant source files. It is acceptable to mark uncertain areas for follow-up rather than inventing explanations.\n\nThe central rule is that documentation must evolve with the code. When behavior changes, the relevant docs should change too. This makes the repository easier to understand, easier to review, and safer for agentic development.\n\nThis documentation system works especially well with MDTS, a local Markdown documentation viewer.\n\nRun MDTS from the repository root:\n\n```\nnpx mdts\n```\n\nThe command opens a browser page for exploring the Markdown documentation in the repository. It puts the project's Markdown files in one place so you can click through the documentation and move between related pages more easily.\n\nReaders can click around linked documentation files and move between related docs. This makes source maps, related-doc links, ADR links, glossary links, and flow links more useful during planning, review, onboarding, and debugging.\n\nBecause `npx`\n\nmay download and execute MDTS from npm, users are responsible for reviewing and trusting the package before running the command.\n\nMDTS does not yet support viewing non-Markdown files. That means links to source files, configuration files, and other non-Markdown project files may not be viewable inside the MDTS browser page yet. There is an [open issue requesting support for common non-Markdown file types](https://github.com/unhappychoice/mdts/issues/830). If that support is added, MDTS could become a lightweight way to review project documentation and related repository context without extra documentation infrastructure or configuration.\n\nThe structure in this document is a starting point. Projects can add documentation categories when they have recurring needs that do not fit systems, flows, architecture, or glossary documentation.\n\nFor example, a project with recurring deployment, migration, incident, rollback, or data-repair procedures may add `docs/operations/`\n\nor `docs/runbooks/`\n\n. Choose one convention for the repository and include it in `docs/README.md`\n\nand the docs map in `AGENTS.md`\n\n. Keep these extensions focused on durable project needs instead of creating categories in advance.", "url": "https://wpnews.pro/news/a-repo-local-markdown-documentation-system-that-helps-humans-and-ai-agents-a-the", "canonical_source": "https://gist.github.com/lukewilson2002/cb48062397d8b51954034d94b8c19d6d", "published_at": "2026-07-09 19:04:31+00:00", "updated_at": "2026-07-10 00:05:11.947015+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents"], "entities": [], "alternates": {"html": "https://wpnews.pro/news/a-repo-local-markdown-documentation-system-that-helps-humans-and-ai-agents-a-the", "markdown": "https://wpnews.pro/news/a-repo-local-markdown-documentation-system-that-helps-humans-and-ai-agents-a-the.md", "text": "https://wpnews.pro/news/a-repo-local-markdown-documentation-system-that-helps-humans-and-ai-agents-a-the.txt", "jsonld": "https://wpnews.pro/news/a-repo-local-markdown-documentation-system-that-helps-humans-and-ai-agents-a-the.jsonld"}}