avizmarlon/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

Every non-trivial software project must maintain these living artifacts in the repository. This applies universally to all projects and teams:

Core Artifacts

| Artifact | Purpose | Format | |---|---|---| | Spec / Charter / README | What the project is, scope, non-goals, decided constraints | Markdown; updated as scope changes | | ARCHITECTURE.md | System structure, component interfaces, security invariants, extension points | Markdown; keep synchronized with code structure | | CHANGELOG.md | Versioned record of all changes, using Keep a Changelog format | One entry per significant change, newest at top | | ADRs (Architecture Decision Records) | Immutable records of architectural and technology decisions | Numbered files in docs/adr/ (e.g., ADR-001-title.md) or single file ARCHITECTURE-DECISIONS.md; format: Title, Number, Date, Status, Context, Decision, Consequences | | SESSION-HANDOFF.md | State transfer between sessions for multi-session or multi-phase projects | Markdown; preserve unresolved entries; never delete without justification | | REVIEW-DECISIONS.md | Decisions made during formal reviews (security, performance, architecture) | Markdown; record Decision + Rationale + Approver + Date | | docs/review/ | Version-controlled review reports | Numbered by pass (charter-review-pass-01.md, charter-review-pass-02.md, etc.); never overwrite |

Artifact Obligation Matrix

| Artifact | Required When | |---|---| | Spec, CHANGELOG, ARCHITECTURE | Any non-trivial project | | ADRs | Any non-trivial architecture, technology, or process decision | | SESSION-HANDOFF | Multi-phase, multi-session, or long-running projects | | REVIEW-DECISIONS | From first formal review onward | | docs/review/ (numbered) | From first review pass onward |

ADR Format (Minimal)

# ADR-NNN: [Title]

**Status:** Proposed | Accepted | Superseded | Deprecated

**Date:** YYYY-MM-DD

## Context
[Problem or requirement that prompted this decision]

## Decision
[What was decided and why]

## Consequences
[Expected outcomes, trade-offs, downstream impacts]

Mark superseded ADRs with a reference to the new ADR that replaces it; never delete old ADRs.

Review Report Naming

Each review cycle gets a new numbered file:

• charter-review-pass-01.md — first review
• charter-review-pass-02.md — second review (addresses feedback from pass-01)
• And so on

Never overwrite prior reports. This preserves the audit trail of iterations and deltas.

Anti-Patterns to Avoid

• Decision in chat only → disappears in next session. Chat decisions are not recorded until written to a project artifact in the same session.
• Single review report overwritten each cycle → loses delta, loses audit trail. Use versioned filenames.
• CHANGELOG placeholder while code evolves → invisible debt. Keep CHANGELOG current.
• "ADR in author's head" → next developer or AI session redoes the decision, possibly incorrectly. Write ADRs.
• Spec deleted after implementation → next feature lacks context for similar decisions. Keep specs.
• README outdated after API change → users/developers follow broken instructions. Sync README with code.

The Core Rule

Conversation + decision without a written record in an artifact = did not happen.

If something was decided in chat and not written to a file in the same session, assume it is lost for the next session. This applies universally to all AI agents, team members, and future developers.

New features, architectural decisions, bug fixes, and design trade-offs must all be recorded before work is considered complete. The record is the contract for the next person or AI who picks up the work.

Implementation Checklist for Contributors

Before marking work as done:

• ] Spec exists for the feature (if applicable)
• ] Code changes are reflected in CHANGELOG
• ] ARCHITECTURE.md is updated if structure changed
• ] API documentation is updated if API changed
• ] New integrations have documented endpoints and auth flows
• ] Non-trivial logic has unit tests
• ] External integrations include logging per project standard
• ] All ADRs for new decisions are written and committed
• ] Documentation is in git (not pending a separate PR or forgotten)
• ] If multi-session, SESSION-HANDOFF.md is updated with remaining work

Documentation as the Contract

Documentation is not a nice-to-have. It is the binding contract between the implementer (developer or AI) and the maintainer (future developer or AI). Code changes are only complete when they are documented.