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
- 最近更新
- 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
- 参考文档README.md1.8 KB
- 参考文档references/architecture-md-schema.md3.5 KB
- 参考文档references/design-know-how.md8.7 KB
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:
- Module split and dependency direction — which modules exist, which may depend on which, and which never.
- Main technology choices — language, framework, key libraries, where the existing code has not already settled them.
- Folder structure — where each kind of file goes (code, tests, scripts), and the size a file stays under.
- 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
using-loom-workflow
Route broad Loom workflow-tool requests to the right skill. Use when the request spans tools or the right workflow skill is unclear.
skill-retro
Review selected past or current Claude Code or Codex sessions against readable target skill sources and related integration. Produce source-linked proposals without applying changes.
recap-state
Give an in-session recap of current progress for 'where were we', '我們剛剛在幹嘛', '剛剛講到哪', '我跟丟了', 'ちょっと振り返って', '今どこだっけ', or '振り返り'. The built-in /recap is an away-summary.
project-retro
Review one current or specified coding session for source-backed project development improvements. Use for a requested retrospective, including 振り返り seeking improvements; not for current-progress recaps or recurring skill mining.
loom-visualization
Show comparisons, flows, decisions, states or reasoning chains as tables, ASCII or Mermaid in coding chat, including when a Loom station reports to the user (intent restatement, choices, acceptance test results); not Obsidian notes.
loom-memory
Record repo-wide lessons when saving to your own memory or asked to remember; recall, reconcile, or forget them when a task needs it.