Sopaco

Posted on Sep 5

Architecture Docs Always Outdated? Let Code "Grow" Them Automatically

#architecture #documentation #github #softwareengineering

Terrain — prepares the ground so agents don't have to guess where to stand.

🔗 GitHub: https://github.com/sopaco/terrain

The Tech Lead's Pain: Documentation as Technical Debt

As a Tech Lead, you've definitely experienced:

Architecture docs that took two weeks to write become unrecognizable after one iteration
Every code review requires explaining "that's not how it's actually designed anymore"
When newcomers ask "how is this system organized?" you can only answer verbally because the Wiki is long outdated
When you ask a new AI assistant to explain the system architecture, it can only guess from the code

Once architecture docs drift from code, they become liabilities—worse than having no docs at all.

Terrain's solution: let documentation emerge from code automatically, instead of being manually written from memory.

Knowledge Factory: Code as the Source of Documentation

Terrain's core is a "knowledge factory"—starting from a Git repository, it auto-generates three layers of documentation:

Git Code Repository
    │
    ├── scan ──► index.md (Project Index)
    │
    ├── pack ──► repomix.md (Source Index)
    │
    ├── context (LLM) ──► agent/context.md (Agent Macro Architecture Context)
    │
    ├── docs (ACP) ──► human/ (Five C4 Architecture Docs + Mermaid Diagrams)
    │
    └── track ──► freshness.json (Freshness Score)

Five C4 architecture documents auto-generated, covering all levels from containers to code, with Mermaid diagrams.

Why Can It Stay "Always in Sync"?

Incremental Updates Instead of Full Regeneration

Traditional documentation tools regenerate everything each time. Terrain doesn't:

Tracks Git HEAD — Precisely knows which files changed since the last scan.
Only regenerates changed portions — Changes involve a module → update corresponding C4 doc; unrelated modules → reuse existing artifacts.
Baseline ledger — Records the Git HEAD for each scan; subsequent refreshes do incremental diffs only.

This means refreshing knowledge for a large project might take seconds instead of minutes.

Freshness Scoring System

Every knowledge asset carries a freshness score, based on:

Git code change volume vs. documentation's last generation time
CodeGraph symbol graph drift detection results

When the score drops below 50, Agents automatically reduce the weight of that knowledge asset—ensuring incorrect suggestions are never made based on outdated architectural information.

The project list interface clearly displays each project's freshness score. Stale assets are instantly visible.

Dual-Track Output: Human-Readable, AI-Consumable

Audience	Document Path	Format
Human Developers / Tech Leads	`.terrain/human/`	Narrative C4 docs + Mermaid diagrams
AI Coding Assistants	`.terrain/agent/context.md`	Structured architecture overview (≤ 14 KiB)
AI Source Retrieval	`.terrain/agent/repomix.md`	Repomix source packs
Business Knowledge	`.terrain/knowledge/`	Glossary and internal conventions

C4 docs cover four levels: Container → Component → Code → Dynamic, paired with Mermaid diagrams, unfolding layer by layer from macro architecture to micro implementation.

Source-First Trust Model

When documentation conflicts with code, Terrain follows clear priority:

repomix source code > CodeGraph symbol graph > context.md > human docs

This isn't empty talk—repomix packages real source code, CodeGraph indexes real symbol relationships. Architecture docs are just "visual interpretations" of source code. When interpretation conflicts with source, source code is always right.

Four-Phase SDD: Making Design Reviewable

Terrain's SDD (Specification-Driven Development) workflow divides development into four phases, each producing reviewable Markdown artifacts:

Phase	Output	Execution Engine
Requirements Analysis	`1.requirements.md`	Native LLM
Technical Design	`2.tech-design.md`	Native LLM
Code Generation	`3.implementation.md` + repo changes	ACP Agent
Code Review	`4.code-review.md`	Native LLM

SDD four-phase workflow. Each phase produces reviewable Markdown artifacts that Tech Leads can examine step by step.

This means Tech Leads can:

Review whether requirements specifications are accurate
Examine whether technical design is reasonable
Confirm whether code generation matches the design
Verify whether code review is thorough

Every step is documented and traceable. Every step is reviewable.

Quick Start

# Initialize a project (auto-generate C4 docs and Agent context)
terrain init ./my-repo

# View architecture overview
terrain project overview --project my-repo

# Run SDD requirements analysis phase
terrain sdd run --project my-repo --phase requirements

# Refresh knowledge (incremental, only update changed parts)
terrain refresh ./my-repo

Who Is This For?

Tech Leads — Architecture docs never go stale, always in sync with code.
Architects — C4 docs auto-generated from code, eliminating massive maintenance overhead.
Team Managers — New member onboarding compressed from days to minutes.
Code Reviewers — SDD workflow makes every design step traceable and reviewable.

"Great architecture isn't written—it grows from code."

DEV Community