Living architecture remembers why

Description and use

Agents can safely modify code by referencing explicit design principles and archived reasoning, reducing error risk.

Problem

Agents need to understand why code exists to safely modify it.

Outcome

Agents can safely modify code by consulting explicit design documents and archived reasoning, reducing errors and aligning changes with current architecture.

Workflow

• Identify affected modules via LikeC4 model
• Retrieve .arc42.md design principles for those modules
• If no relevant principles, fetch archived OpenSpec docs from PR history
• Analyze reasoning behind original code changes
• Determine which of the three cases applies (core design, legacy reason, or arbitrary choice)
• Proceed with code modification respecting the identified case
• Merge PR and archive new OpenSpec change
• Update design principles if necessary

Evidence

The core normative design principles of a module are spelled out explicitly by the human in an .arc42.md document attached to the respective node

Source

Each PR workflow interviews the human about corner cases and design choices, and creates a complete set of OpenSpec artefacts, scenarios, design doc, and all

Source