The Failure of State-Heavy Documentation

Documentation rots when it attempts to hold both the decision (the rule) and the current state (the implementation). The author found that sections of a 1,200-line plan describing specific UI flows became obsolete as the code evolved. Because the plan was tied to the current state, it drifted and eventually became a liability. The lesson: documentation should only contain the decision. If it describes the current implementation, it will inevitably go stale.

The Three Shelves for Durable Decisions

To ensure architectural and process rules survive, they must be moved to "shelves" that the code cannot reach or modify. The author identifies three specific mechanisms:

  1. Mechanical Enforcement (Build Graphs): Rules like project-reference restrictions (e.g., preventing the Web project from referencing the API project) are enforced via .csproj files. This creates a hard constraint that prevents code drift. The explanation for why the rule exists lives in CLAUDE.md, while the what is enforced by the compiler.
  2. Persistent AI Memory: When fixing bugs or architectural issues, the author inputs the solution into the AI's project memory before applying it to the code. This ensures that future sessions inherit the correction (e.g., "seed scripts must be idempotent") without the developer needing to re-derive the fix. This prevents the same mistake from being made twice.
  3. External Calendars: Dependencies with long lead times (e.g., Apple/Google developer account approvals) should not live in a project plan document, as they are easily ignored during feature reshuffling. They belong on a calendar. The author notes that treating provisioning as a critical path item on a calendar is the only way to ensure it survives the reality of development.

The Cost of Deferred Reality

By failing to put external provisioning on a calendar, the author built a complex payment system (Stripe, Apple, Google) that could not be tested because the necessary external accounts were not yet approved. This serves as a proof-by-counterexample: code can be perfectly architected and unit-tested, but if the external dependencies are not managed as a hard-dated constraint, the project remains blocked. The retroactive rule is to identify all paid external dependencies on day one and map their approval clocks to a calendar, not a text document.