Repository Knowledge as System of Record
This principle emphasizes structuring and maintaining all critical system knowledge directly within the code repository, making it the authoritative “system of record.”
Key Takeaways
- The repository should contain versioned, structured information (code, docs, plans) as the primary source of truth.
- This approach avoids the pitfalls of monolithic, easily outdated instruction manuals.
- It enables “progressive disclosure” of information, crucial for AI agents.
- Mechanical validation (linters, CI jobs) ensures the knowledge base remains up-to-date and consistent.
Main Concept
Instead of relying on external documents or large, unmanageable instruction files, the repository itself becomes the central hub for all essential information. This includes design documentation, architecture maps, quality grades, technical debt tracking, and execution plans. All these artifacts are versioned alongside the code, ensuring they remain synchronized and accessible. This makes knowledge discoverable and verifiable, which is particularly important for AI agents that need reliable context to perform complex tasks.
Practical Use
- AI Agent Effectiveness: Provides agents with consistent, up-to-date context, reducing errors and improving task completion.
- Onboarding: New developers (human or AI) can quickly understand the system’s state and history.
- Maintainability: Ensures documentation and design decisions evolve with the codebase.
- Traceability: Allows for easy tracking of decisions, plans, and their implementation status.
Implementation Notes
- Structured
docs/Directory: Cataloging and indexing design documentation. - Architecture Documentation: Providing a top-level map of domains and package layering.
- Quality Documents: Tracking gaps and quality grades over time.
- Execution Plans: Versioned plans with progress and decision logs for complex work.
- Progressive Disclosure: Starting agents with a small, stable entry point and guiding them to deeper information.
- Mechanical Enforcement: Linters and CI jobs validate the knowledge base’s currency, cross-linking, and structure.
- Doc-Gardening Agents: Automated tasks to scan for and fix stale documentation.
Connected Notes
- Agent-First Software Development - How this principle supports agent-driven development.
- Progressive Disclosure - A pattern enabled by this approach.
- Linters - Tools used to enforce knowledge base integrity.
Questions
- What are the best practices for structuring repository knowledge for maximum agent and human readability?
- How can the process of updating and validating repository knowledge be further automated?