docs-as-code

Documentation as Code — Hard Enforcement

Code without documentation is not done. Documentation is context; context is long-term memory for AI agents and future developers. Without it, each new session or developer starts from zero.

Minimum Documentation Checklist (Every Code Session)

For every session involving code changes, this checklist must be satisfied:

• New feature → specification created before implementation (docs/<feature>-spec.md or dedicated section in existing spec)
• Feature added or modified → docs/architecture.md updated with structural changes and impacts
• Any code change → CHANGELOG.md or equivalent with entry for this change
• Public API modified → README documentation for the module/package updated
• New external integration → documentation created with validated endpoints, authentication flow, error handling, and troubleshooting steps
• Non-trivial module logic (caching, retry logic, authentication, scoring/ranking algorithms) → unit tests added before merge
• Module with external integration → structured logging implemented per project standards

Multi-Tool Documentation Sync Gate

All AI agents and developers working on a project must maintain rule parity across tool configurations:

• Rules in project .rules/ or documentation directories must be mirrored in all active development tools (editor configs, linter configs, etc.)
• Global instruction files (e.g., CLAUDE.md, AGENTS.md, etc. when they exist) must stay synchronized
• Any change to documentation rules in one tool = update in all tools, in the same session
• Verify sync by grep-checking the rule text appears consistently across all tool config files

Debt visibility principle: If code changes must skip documentation "for now," explicitly record this as doc-debt in a visible location (session-handoff.md, PROGRESS.md, or backlog). Invisible debt is unacceptable; visible debt can be tracked and cleared later.

Required Documentation Ledger