authoring-architecture-docs（创作架构文档）

Authoring Architecture Docs Action

Produces architecture decision records, design documents, and C4 Model diagrams scoped to the appropriate level for the current SDLC phase and audience — the understanding-oriented quadrant of the Diátaxis framework. Diagrams are scoped to the appropriate level for the current SDLC phase and audience.

Load authoring-technical-docs first for the multi-pass workflow, style rules, and quality framework. This action provides the templates and architecture-specific rules.

References

Read these before executing any step.

Assets

Use these as output scaffolding.

Workflow

Step 1 — Read references

Read all four files in references/ before any other action.

Step 2 — Gather project context

Extract from input. Ask only if a required field is missing.

Step 3 — Select diagram levels

Consult references/sdlc-mapping.md → Phase Matrix and Audience Decision Tree. State the selection and rationale before proceeding.

Step 4 — Produce each diagram

For each selected level, in order:

1. Open assets/diagram-templates.md and copy the matching template section
2. Fill every {{placeholder}} — leave none blank
3. Apply all rules from references/level-rules.md for that level
4. Scan output against references/anti-patterns.md
5. Self-check against the Review Checklist in assets/architecture-doc.md

Step 5 — Assemble output document

Open assets/architecture-doc.md as the document scaffold. Insert completed diagram sections in level order: L1 → L2 → L3 → Deployment → Dynamic. Complete the Key Architectural Decisions table and Change Log.

Step 6 — Save files

docs/architecture/ARCHITECTURE.md
docs/architecture/diagrams/context.mermaid
docs/architecture/diagrams/container.mermaid
docs/architecture/diagrams/component-{{container_name}}.mermaid
docs/architecture/diagrams/deployment.mermaid
docs/architecture/diagrams/dynamic-{{flow_name}}.mermaid

Save only the files corresponding to the levels actually produced.

Inputs

• Project description, README, or source code
• SDLC phase (required)
• Target container name and source structure (L3 only)
• Flow name and steps (Dynamic only)

Outputs

• ARCHITECTURE.md — full assembled documentation package
• diagrams/*.mermaid — one file per diagram level produced

Architecture docs rules

1. Separate "what is" from "what should be." Overviews describe current state. Design docs describe proposed future.
2. Diagrams are not optional. Use Mermaid — it's version-controllable.
3. Include the "why." Link to ADRs.
4. Write for the new team member.
5. Be honest about trade-offs. Every architecture has weaknesses. Document them.
6. Link to code. When describing a component, link to the relevant repo or entry point.

Using Mermaid for diagrams

Accompany each diagram with a brief prose summary (2–4 sentences) explaining the key relationships shown.

System overview:

graph TB
    User[User] --> WebApp[Web Application]
    WebApp --> API[API Service]
    API --> DB[(Database)]
    API --> Queue[Message Queue]
    Queue --> Worker[Background Worker]
    Worker --> DB

Sequence diagram:

sequenceDiagram
    participant Client
    participant API
    participant DB
    Client->>API: POST /resources
    API->>DB: INSERT resource
    DB-->>API: resource_id
    API-->>Client: 201 Created

Example Triggers

• "Generate a C4 context diagram for this project"
• "Show me the container architecture"
• "Document the components in the auth service"
• "Create a class diagram for the payment module"