AGENT SKILL

architecture-design

Design and ratify ARCHITECTURE.md with the user: module boundaries, tech choices, folder layout, CI stages, then guard tests. Use to design or change a project's architecture. 架構設計 / 架構規則 / アーキテクチャ設計.

License 许可
MIT
所属仓库
kouko/loom-plugins
最近更新
2026-11-15
Stars
★ 0
Forks
0

01 前言 Front Matter

name
architecture-design
version
1.0.0
description
Design and ratify ARCHITECTURE.md with the user: module boundaries, tech choices, folder layout, CI stages, then guard tests. Use to design or change a project's architecture. 架構設計 / 架構規則 / アーキテクチャ設計.

02 资源文件 3

03 SKILL.md 正文

What this tool does

Relative paths in this document are relative to this skill's own directory.

Deliver local documents with actual absolute paths from the active worktree or external location, including in copyable instructions. For known local Markdown support, use the document's project-relative path as link text (external files: basename) and absolute targets; otherwise show full absolute paths. Enclose targets with spaces in angle brackets: [doc.md](</worktree name/doc.md>). Preserve bundled references, stored relative paths, quoted examples and incidental filenames.

The user asks for an architecture for a repository. You design it with the user — read what exists, propose options with trade-offs, let the user pick — then draft ARCHITECTURE.md in a temporary copy holding the decisions and the rules only, write a guard test for every rule that can be checked mechanically, restate them, and — on "yes" — write the ratified-by: line and install the ratified document and guards. For a shared editable diagram during discussion, use loom-workflow:loom-interactive-diagram.

Step 1 — When to run

When architecture boundaries or tradeoffs depend on missing consequential evidence, identify the decision and use loom-design:design-research as needed. Reuse adequate evidence directly; return findings or uncertainty to this task while preserving user choices, scope and ratification authority.

Run this on request only. ARCHITECTURE.md is never required: an absent or unratified ARCHITECTURE.md never blocks a change, at any station.

When ARCHITECTURE.md already exists, run in re-design mode. Keep the ratified root document and its active guards unchanged while drafting in a temporary copy. When a change alters the structure, re-design only the affected part with the user (Step 2, for the affected choices alone), then update the affected decisions, rules and guards in the same commit, run the validator, and re-ratify (Step 4) — a decision, rule or guard changed without the others leaves the document and the suite disagreeing.

Step 2 — Design with the user → ARCHITECTURE.md

Read first. Read the project's requirements — its intent files, README and PRINCIPLES.md, when present — and the existing code: its layout, languages, build files, test setup and CI, if any.

Propose. The open choices are:

  1. Module split and dependency direction — which modules exist, which may depend on which, and which never.
  2. Main technology choices — language, framework, key libraries, where the existing code has not already settled them.
  3. Folder structure — where each kind of file goes (code, tests, scripts), and the size a file stays under.
  4. Required CI stages — what CI must run, and in what order.

A choice the existing code already settles is stated, not re-opened — unless the user asks to revisit it. For each open choice, present at least two options in MADR style: the decision drivers first, then each option's trade-off against those drivers ("good, because … / bad, because …"), then your recommendation and what would make it wrong. Never present a single answer, even when one option looks obvious. Draw the options from references/design-know-how.md. The user picks; on a question, answer it and present the options again.

Data models and API interfaces stay out of this design: they belong to each change's spec.

Write. Work in a temporary copy of the repository outside its normal test discovery paths. Write the draft ARCHITECTURE.md at that copy's root, without a ratified-by: line, following references/architecture-md-schema.md: a title, a ## Decisions section recording each pick (the choice, the options considered, the reason), then exactly the four rule sections, one line per rule, and no overview or background section.

Step 3 — Write the guards and validate

In the temporary copy, for every rule that can be checked mechanically, write a guard test in the repository's own test framework, under a path its package-tests: command in docs/loom/KICKOFF-DEFAULTS.md already runs — or extend that command so it does; a guard the suite never runs holds nothing. When that file or its package-tests: line is absent or none, propose the repository's test command to the user and record it there as - package-tests: <command> — <reason> (<date>) before writing guards. Record the guard's path on the rule line (check: <guard path>). A rule that needs judgment says check: review and gets no guard.

Each guard's failure message follows the schema's "Guard failure message" section. Run the guards once in the temporary copy; a guard that fails on today's code is either a rule the user must restate or a violation to show them.

Then check the file, with <loom-design> standing for this plugin's own checkout:

python3 <loom-design>/scripts/architecture-design/validate_architecture_output.py ARCHITECTURE.md --draft

Exit 0: go to Step 4. Non-zero: fix what it names and run it again. Never read back a file that has not exited 0 here.

Step 4 — Restate and ratify

Read every decision and rule back to the user in plain words, with which rules a guard checks and which a reviewer judges. On a correction, fix it and read back again. On "yes" — and only then — write one line directly under the title:

ratified-by: <name> <date>

<name> is the user's own name or handle; <date> is today, YYYY-MM-DD. Run the validator again without --draft in the temporary copy. On success, install the ratified document, guards and associated suite configuration in the working repository together, replacing the old versions in re-design mode. Activate the guards only after ratification. Run the normal suite; never commit an unvalidated draft as the active architecture.

Step 5 — Commit

Add ARCHITECTURE.md, the guard files, and every file Step 3 edited so the suite runs the guards (docs/loom/KICKOFF-DEFAULTS.md, test or tool config) by name, then:

git commit -m "docs(loom): ARCHITECTURE.md ratified"

Downstream — how the rest of the flow uses it

write-plan reads ARCHITECTURE.md, when ratified with the existing ratified-by: <name> <date> line, before its Task DAG: it places added or moved files by the rules and names the rule id on the task's Risk line. At closing-review, the code lens dimension architecture-conformance scores the diff against the rules — a violation is a finding with a fix; with no ratified ARCHITECTURE.md the dimension is scored N/A with a one-line reason. A missing ARCHITECTURE.md is only the standing WARN the checker prints and never blocks any station.

04 同仓库更多 Skills