architecture-first
Decide module boundaries before the first file: what modules exist, which way dependencies point, who owns state, and what each module may know. Use when starting a project, service, site, API, or subsystem; adding a feature with no obvious home; resolving a circular import or inverted framework dependency; or writing an ARCHITECTURE.md or ADR. Do not use for a one-file script, throwaway experiment, bug fix inside an established seam, naming/function-shape cleanup (use code-complexity), an existing oversized module (use refactoring-safely), or capacity/data scaling decisions (use system-and-data-design). This defines earned boundaries; it does not license speculative layers.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- architecture-first
- description
- Decide module boundaries before the first file: what modules exist, which way dependencies point, who owns state, and what each module may know. Use when starting a project, service, site, API, or subsystem; adding a feature with no obvious home; resolving a circular import or inverted framework dependency; or writing an ARCHITECTURE.md or ADR. Do not use for a one-file script, throwaway experiment, bug fix inside an established seam, naming/function-shape cleanup (use code-complexity), an existing oversized module (use refactoring-safely), or capacity/data scaling decisions (use system-and-data-design). This defines earned boundaries; it does not license speculative layers.
02 资源文件 12
- 参考文档references/clean-architecture-original.md13.3 KB
- 参考文档references/clean-architecture/boundaries-and-layers.md53.3 KB
- 参考文档references/clean-architecture/details-and-code-organization.md45.0 KB
- 参考文档references/clean-architecture/python-implementation.md68.1 KB
- 参考文档references/clean-architecture/solid-and-components.md46.7 KB
- 参考文档references/domain-driven-design-original.md18.7 KB
- 参考文档references/domain-driven-design/bounded-contexts.md13.1 KB
- 参考文档references/domain-driven-design/building-blocks.md13.1 KB
- 参考文档references/domain-driven-design/domain-events.md11.8 KB
- 参考文档references/domain-driven-design/repositories-factories.md15.0 KB
- 参考文档references/domain-driven-design/strategic-design.md14.2 KB
- 参考文档references/domain-driven-design/ubiquitous-language.md12.4 KB
03 SKILL.md 正文
Architecture first — the shape before the first file
Most bad structure is not a bad decision. It is an absent one: code goes where the smallest diff puts it, and the smallest diff is always "next to the last thing". This skill exists to make the layout an explicit, cheap, early decision.
Scope guard — read first
Match the ceremony to the problem. Over-applying this is its own failure mode.
| Situation | What this skill asks of you |
|---|---|
| Script, spike, one file, throwaway | Nothing. Skip. |
| One module, <500 lines, one reason to change | Name the module and its one job. Stop. |
| Service / site / API, several concerns | The full pre-code checklist below. |
| Multiple teams or deployables, shared domain | Checklist + bounded-context map + one ADR per boundary |
| Multi-stage work or external release prerequisite | Checklist + a small stage map before the first implementation boundary |
The one law
Dependencies point inward, toward policy. Business rules must not import the web framework, the ORM, the queue, or the file layout. The reverse is required.
Violating it silently is the failure — a violation that is written down, with the reason and the cost, is a decision. A violation nobody named is erosion.
Practical test: could this module be exercised by a test with no network, no database and no framework? If not, something outer leaked inward.
Pre-code checklist — before the first file
- Name the modules by reason to change, not by technical layer.
queue,billing,catalog— notcontrollers,models,utils. A module that changes for two unrelated reasons is two modules. - Say what each module owns. Especially state: every piece of mutable state has exactly one owning module, and everyone else asks that module. Module-level mutable state shared across features is the coupling that later makes a split expensive.
- Draw the dependency arrows. Any cycle is a design bug, not a build inconvenience. Any arrow from domain to framework is inverted — fix it with an interface owned by the inner side.
- Establish the ubiquitous language. One term, one meaning, in code and in speech. If the same word means different things in two places, you have found a bounded context boundary — draw it there.
- Define the aggregates. What must be consistent in one step, and what may lag. Transaction boundaries follow this, not the other way round.
- Write one vertical slice end-to-end — UI to store to test — before broadening. A slice that works proves the seams; six half-built layers prove nothing.
- Record it. One page: modules, ownership, data flow, external systems. Plus one short ADR per decision that was genuinely a choice (context, options, decision, consequences). Both live in git, next to the code.
- Name the promotion boundaries. When one verified result becomes the input to
another stage, name its contract, inputs, output, and invalidation keys before
implementation. A missing signer, VM, account, or remote service is a future
BLOCKEDstage, not a reason to keep reopening already-proven code.
Stage contracts - when proof becomes an input
For multi-stage work, architecture includes delivery boundaries as well as module boundaries. Keep these states separate:
VERIFIED: the scoped behavior passed at one exact revision.SEALED: the verified scope has an immutable receipt and may be consumed by a following stage.BLOCKED: a named external prerequisite is absent; upstream proof remains valid.SUPERSEDED: a contract, source, or input digest changed, so a successor must be verified instead of editing history.
The stage map is deliberately smaller than a release plan. For each boundary, name
the owning scope, frozen contract, inputs, output, and what invalidates it. Use the
machine-readable ledger only when there is a real hand-off between stages:
../proof-verify/references/proven-stage-contracts.md. Do not add it to a one-file
change merely because the word "stage" exists.
Review checklist — once code exists
- Does any inner module import an outer one? Name it or fix it.
- Is there module-level mutable state touched by more than one feature?
- Does one file hold routes/handlers for more than one reason to change?
- Are there two names for the same concept, or one name for two?
- Can each module's tests run without the framework?
- Does the ARCHITECTURE.md still describe what is actually there?
Fast decision table
| Question | Default answer |
|---|---|
| Layer folders or feature folders? | Feature (vertical slices). Layer folders scatter one change across four directories. |
| Where does validation live? | Input shape at the edge; business rules inside. Never only at the edge. |
| Interface for a single implementation? | No — until a second caller or a test double actually needs it. |
| Microservices? | Not yet. Modular monolith with real boundaries first; extract when a module needs its own deploy or scaling. |
| Where does the ORM model live? | Outer. The domain object is not the row. |
| Shared "utils" module? | A smell. Utils is where things go when nobody decided; name the reason instead. |
References — load on demand
references/clean-architecture/boundaries-and-layers.md— boundaries, Humble Objectreferences/clean-architecture/solid-and-components.md— SOLID applied correctly, REP/CCP/CRP, ADP/SDP/SAPreferences/clean-architecture/details-and-code-organization.md— DB/web/frameworks as detailsreferences/clean-architecture/python-implementation.md— entities, use cases, repositories, wiringreferences/domain-driven-design/bounded-contexts.md— context mappingreferences/domain-driven-design/ubiquitous-language.md— one term, one meaningreferences/domain-driven-design/building-blocks.md— entities, value objects, aggregatesreferences/domain-driven-design/domain-events.md,repositories-factories.md,strategic-design.md*-original.md— the source skills' own framework prose, kept verbatim
Gotchas
- "We'll structure it later." Later costs more per caller, and callers only grow. The cheapest moment is before the first file; the second cheapest is now.
- Ceremony as architecture. Four layers around a CRUD endpoint is not architecture, it is cost. The scope guard above exists to stop this.
- Folders instead of boundaries. Moving files without changing who imports whom changes nothing. The arrows are the architecture; folders only display it.
- The domain importing the framework "just for a type". That is the whole violation, arriving politely.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Circular import | Two modules both own part of one concept | Extract the shared concept into a third module both depend on |
| One change touches six files across four folders | Layer folders, not feature folders | Re-cut by feature; keep the change local |
| Tests need a live database to assert a rule | Rule lives outside the domain | Move the rule inward, inject the store |
| Nobody can say which module owns X | Nobody decided | Decide now, write it in ARCHITECTURE.md, move the state |
04 同仓库更多 Skills
owner-voice
暂无简介
humanize-russian
Редактировать русский текст для ясности и естественного звучания, сохраняя факты, термины, источники и жанр. Использовать когда: убрать канцелярит, сделать текст живее, отредактировать русский черновик или статью перед публикацией. Не определяет авторство и не обещает обход детекторов. Для английского — humanize-english; для структуры и доказательств — article-structure-review.
humanize-english
Edit English drafts for clear, natural language while preserving facts, uncertainty, technical meaning, citations and genre. Use when: humanize this text, remove AI-style filler, improve English prose, or edit an English article before publication. Not an authorship detector or a promise to bypass one. For Russian use humanize-russian; for thesis/evidence and structure use article-structure-review.
caveman
Ultra-compressed reply mode. Cuts output tokens ~65-75% by answering in terse "caveman" style while keeping full technical accuracy, and shapes what survives: action first, state restated every turn, concrete time estimates, visible wins. Intensity levels: lite, full (default), ultra, wenyan-lite, wenyan-full, wenyan-ultra. Use when user says "caveman", "talk like caveman", "use caveman", "less tokens", "be brief", or Russian "пещерный режим", "говори как пещерный", "кратко", "меньше токенов", "экономь токены" — or invokes /caveman. Preserves the user's language (Russian in → Russian caveman out). Off only: "stop caveman" / "normal mode" / "обычный режим". Do not use merely because a response should be concise, and do not use when the user requests normal prose, a polished document, or exact wording.
article-structure-review
Проверить структуру технической статьи после черновика: задача читателя, жанр, опора значимых утверждений на доказательства и честные ограничения. Use after the first draft, before publication. Исправлять структуру, когда это входит в запрос; не создавать обязательный конвейер из других навыков. Для локальной языковой редактуры — humanize-english или humanize-russian.
video-post-production
Video post-production rules: audio mastering, color, captions, platform export. Use when: 'add music', 'add voiceover', 'export for tiktok', 'add captions', 'color grade', 'audio levels', 'master audio', 'export settings', 'platform requirements'. Covers FFmpeg patterns, audio chain, subtitle standards, and platform-specific export configs. Do NOT use to generate or animate the video frames/scenes in code (use remotion-production-guide), to write the script (use video-narrative-arc), or to evaluate script quality (use script-evaluator); this is the finishing stage applied to an already-rendered video.