#
Overview
This specification establishes an automated, agent-driven software architecture documentation ecosystem. The framework integrates strict structural standards, controlled natural language rules, and autonomous AI maintenance patterns into a unified, version-controlled pipeline.
#
Core Pillars
- Structural Standard (arc42 & C4 Model)
System Decomposition: All documentation follows the hierarchical arc42 architecture template, ensuring complete coverage from business goals down to deployment views and quality requirements. #
Visualizations: The C4 model (Context, Containers, Component, Code) is embedded directly into source files using Mermaid.js or Structurizr DSL to maintain living visual artifacts alongside text.
- Linguistic Standard (ASD-STE100)
Controlled Vocabulary: All documentation must adhere to ASD-STE100 (Simplified Technical English) principles. #
Clarity Constraints: Sentences remain concise, active voice is strictly enforced, and synonyms are eliminated to ensure absolute zero ambiguity for both human readers and machine interpreters.
- Agentic Maintenance Pattern (Karpathy-Style Workflow)
Living Codebase Model: Documentation is treated as a compiled artifact maintained primarily by AI coding agents rather than manual wiki updates. #
Repository Governance: A root-level configuration file (AGENTS.md orCLAUDE.md ) acts as the compiler rulebook, dictating formatting, terminology, and structural constraints to any interacting AI agent.
#
Operational Workflow
Storage: Plain-text documentation sources (AsciiDoc or Markdown) reside in a version-controlled repository structured according to arc42 layouts. #
Execution: Architectural changes trigger targeted agentic instructions. Agents read repository guardrails, update affected multi-file documentation blocks, log corresponding Architecture Decision Records (ADRs), and refresh C4 diagrams in a single pass. #
Publishing: CI/CD automation compiles the source files into a static architecture portal on every commit.