A constraint left only in a conversation can disappear when a coding agent’s context is compacted. A durable artifact preserves articulated intent beyond that session so future work does not depend on memory or on inferring decisions from code. section 1.3 section 2.4.6
Specifications and tests are durable artifacts when they capture decisions, constraints, and verifiable outcomes. They seed the context for an agent’s implementation and verification. The artifact is the primary control surface; generated code is an expression of it, not a substitute for it. section 1.3 section 1.4
Keep the artifact useful across changes:
- Use structured dialogue to clarify a small feature, then record its requirements, technical approach, and execution tasks in reviewable form. section 2.5.1 section 2.6
- When proposing a change, consult existing specifications for both current behavior and the reasons behind it; review the new proposal for risks and unintended effects. section 2.4.6
- If implementation exposes a missing requirement, correct the intent artifact and regenerate the implementation rather than treating a direct code patch as the lasting fix. section 2.5.1
Changing URL expiry
Suppose a URL-shortening service must make all short URLs expire on the 90th day. Existing specifications retain earlier decisions while a new proposal records that the change also affects stored mappings. Reviewing that proposal before implementation exposes impacts that would be easy to miss if the agent had only the current code and a fresh prompt. section 2.4.6
Listing 2.11 Excerpt from proposal.md for changing URL expiry logic
### Modified Capabilities - `url-shortening`: short URLs now have a fixed 90-day lifetime, including existing mappings already stored in the service.
The proposal excerpt explicitly marks URL shortening as a modified capability and includes existing mappings in the 90-day rule. section 2.4.6
