Use when system design and OpenAPI spec exist and subsystem-level design documents are needed — invoked per-person, per-subsystem to produce implementation design with internal flows, data structures, exception handling, and DFX
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Use when system design and OpenAPI spec exist and subsystem-level design documents are needed — invoked per-person, per-subsystem to produce implementation design with internal flows, data structures, exception handling, and DFX
Transform system design and API contracts into a subsystem-level implementation design document that strictly follows the template at config.templates["subsystem-design"] (default: templates/subsystem-design-template.md). Each invocation handles ONE subsystem — multiple subsystem owners invoke this skill independently.
Input: System-level design document + OpenAPI spec (produced by design-spec)
Output: One subsystem-level design document, as a directory of chapter files under the shared project output directory
Core principle: No empty chapters, mandatory Mermaid sequence diagrams with alt/else branches, SQL DDL for database tables, DFX coverage mandatory, API references point to OpenAPI spec (not duplicated), review-ready output.
Extension Points
Before starting, read cospowers.config.json from the plugin root (2 levels above this skill's base directory — the directory shown in "Base directory for this skill" at skill load time). No fallback needed — the config always has valid defaults.
Config field
Used for
config.templates["subsystem-design"]
Template file path for the subsystem design document
config.rules["design-review"]
Design review rules directory
config.rules["dfx"]
DFX rules directory
config.evaluators["subsystem"]
Evaluator skill name dispatched per subsystem (step 6); false = skip
config.evaluators["doc-quality"]
Evaluator skill name dispatched for last subsystem only; false = skip
When to Use
System design + OpenAPI spec exist and YOU need to write YOUR subsystem's implementation design
Each subsystem owner invokes this skill independently for their assigned subsystem(s)
Continuing from system design and API contract artifacts produced by design-spec or another design process
User explicitly requests subsystem design document creation
Don't use when:
System design and OpenAPI spec are not yet defined (use design-spec first)
Simple tasks not requiring design documents (use solution-design only when design artifacts are needed)
Checklist
You MUST create a task for each of these items and complete them in order:
Load system design and OpenAPI spec — scan docs/agent-rules/3-system-design/output/ for subdirectories with YYYY-MM-DD- prefix; take the newest one (sort descending).
1a. Load system design: Read index.md to understand the project and chapter TOC. Read sub-doc 4 (软件方案) §4.2 to extract the full subsystem list. Read sub-doc 4 §4.6 for cross-subsystem interaction flows relevant to interface design.
1b. Load OpenAPI spec: Read <project>-openapi.yaml from the same directory. Extract:
All endpoint definitions grouped by subsystem tag (method, path, request/response schemas)
Error code definitions
Type constraints from API schema definitions
⛔ HARD GATE — OpenAPI must be valid before proceeding.
Check
How to Verify
Blocking?
File exists
ls the path docs/agent-rules/3-system-design/output/YYYY-MM-DD-<project>/<project>-openapi.yaml
YES — STOP if missing
Valid YAML
Parse; confirm it loads without error
YES — STOP if invalid
Has endpoints
At least one paths: entry with a method
YES — STOP if empty
If any check fails: DO NOT proceed. Tell the user:
1c. Select target subsystem: Present the subsystem list from §2.2 to the user:
Present the subsystem list to the user and ask which one they own:
"系统设计包含以下子系统（来自 §2.2）：
...
你负责哪个子系统的设计？"
Scope to ONE subsystem for this invocation. If the user is responsible for multiple subsystems, they invoke this skill separately for each.
Collect subsystem implementation context via init template — for the selected subsystem, gather the owner's knowledge about implementation constraints:
Init template section → subsystem design mapping:
Section
What to extract
Fed into
§1 基本信息
Repo URL, language/framework, owner
Ch.1 of subsystem design doc; required before proceeding
§2 内部架构图
Internal component diagram
Ch.2 module decomposition; verify against knowledge base
§4 技术债务
Known bugs, frozen code, legacy constraints
Flag as [已知债务: ...] wherever they affect design choices
§5 业务规则
Domain rules not visible in code
Add as explicit design constraints, not comments
§6 依赖的外部接口
Known API quirks, limits, failure modes
Ch.5 exception handling; integration notes
§7 其他信息
Any additional context
Background knowledge applied across all sections
Check if docs/agent-rules/4-subsystem-design/input/init-{subsystem-name}-subsystem.md already exists:
If exists and filled: read it, validate, proceed to step 3
If exists but empty or partially filled: tell the user what's still needed, wait for completion
If does NOT exist: read templates/init-subsystem-template.md, pre-fill known info (§1: subsystem name from §2.2, API interfaces from OpenAPI spec), write to the path above, tell the user:
"我已为「{subsystem-name}」生成情报简报，保存在 docs/agent-rules/4-subsystem-design/input/init-{subsystem-name}-subsystem.md，请在 IDE 中打开填写。
§1 基本信息（代码仓库/语言）为必填项，§2 内部架构图强烈建议提供，§4 技术债务务必如实填写。填写完成后告知我。"
Wait for user confirmation before proceeding.
⛔ HARD GATE — Step 2a: Init completeness validation
After reading the filled init template, evaluate information quality. Note: this gate only checks sufficiency of input information (can we start designing?), NOT design quality. The design quality check is step 6's subsystem-evaluator subagent.
Section
Blocking?
Sufficient when...
§1 基本信息（代码仓库/语言）
YES
Repo URL or local path provided and verifiable; language/framework identified
§4 技术债务
YES (explicit answer required)
Either lists specific known issues/frozen code, OR user explicitly writes "无已知债务" — blank is NOT acceptable (silent debt is the most dangerous kind)
§2 内部架构图
No
Diagram is present; if absent, note that module decomposition will be inferred from code
§5 业务规则
No
Domain rules are specific and testable (not just "按业务需求")
§6 依赖的外部接口
No
Known quirks / failure modes are documented for each dependency listed
If any blocking item fails: tell the user exactly what is needed, wait for update, re-read and re-validate. Do NOT begin writing until blocking items pass.
⛔ HARD GATE — Step 2b: Knowledge archival to evo-knowledge-wheel
After completeness validation passes, archive reusable knowledge before designing:
技术债务（§4）: Specific frozen code areas, known bugs with workarounds, or legacy constraints that AI must avoid touching — contribute as "no-go zone" capsules so future design sessions don't rediscover these.
业务规则（§5）: Domain rules invisible in code (state machine constraints, calculation formulas, regulatory requirements) — contribute as domain rule capsules.
外部接口怪癖（§6）: Non-obvious API behaviors, rate limits, failure modes of dependencies — contribute as integration pattern capsules.
内部架构决策: If §2 reveals non-obvious design choices (e.g., "this service uses event sourcing for audit, not CRUD"), contribute as architectural decision capsules.
After archival completes (or if nothing is worth contributing), proceed to step 3.
Write subsystem-level design document — following the template at config.templates["subsystem-design"] (default: templates/subsystem-design-template.md) (master entry + 11 sub-documents). Write in alignment checkpoints: pause after interfaces (Ch.3) and internal design (Ch.4) for user confirmation. API references in ch03 MUST point to the OpenAPI spec from design-spec. Save to docs/agent-rules/4-subsystem-design/output/YYYY-MM-DD-<project>/<subsystem>/.
Responsibility summary: one paragraph on what this subsystem does and does NOT do
Chapter TOC: - [§N Title](chNN-filename.md) — one-line description for each chapter
Cross-chapter consistency check — verify DFX numbers, interface references, terminology, risk completeness, and test-case traceability within this subsystem document (see "Cross-Chapter Consistency Check" section below). Every key flow in Ch.4 and every exception strategy in Ch.5 must have at least one executable test case in Ch.6; each changed public interface must have normal, boundary, and exception cases where applicable.
Subagent review — dispatch a subagent reviewer using skills/subsystem-design-spec/agents/design-document-reviewer-prompt.md. Fix any issues found before step 6.
Quality evaluation (Stage Gate) — dispatch a quality evaluator subagent using the skill name from config.evaluators["subsystem"] (default: subsystem-evaluator) via skills/<evaluator>/agents/evaluator-dispatch-prompt.md. The subagent runs in an isolated context and returns a compact grade + issue list. Apply all Critical/Error fixes. If the document scores < B (< 80): present the issue list to the user and identify which init template sections are relevant — ask the user to supplement those sections, then re-run from step 3.
If config.evaluators["subsystem"] is false, skip this gate and proceed to cross-document check.
Cross-document consistency — dispatch a cross-document evaluator subagent using skills/doc-quality-evaluator/agents/evaluator-dispatch-prompt.md (runs config.evaluators["doc-quality"], default: doc-quality-evaluator). Only runs when ALL subsystems have completed designs under docs/agent-rules/4-subsystem-design/output/YYYY-MM-DD-<project>/. Before dispatching, check: does every subsystem listed in system design §2.2 have a subdirectory here? If any are missing, skip this step — the last subsystem owner to complete their design will trigger the cross-document check.
If config.evaluators["doc-quality"] is false, skip cross-document consistency check entirely.
User reviews design — ask user to review the document, iterate if needed
Transition to implementation — invoke writing-plans
Design Phase AI Roles
Design quality comes from applying the right mode at each stage. Switch modes deliberately.
Writer Mode
Generate design document sections following team templates. The default mode for producing document content.
Challenger Mode
Applied throughout writing. For every design decision:
Ask: "What could fail with this choice?"
Ask: "What am I assuming that hasn't been confirmed?"
Ask: "Is there a simpler alternative I'm dismissing too quickly?"
Force proposing an alternative before committing to the first idea.
Mark unconfirmed assumptions inline as [待确认: reason].
Reviewer Mode
Defines what the subagent reviewer (step 5) checks. These are also the criteria the Writer should be aware of throughout writing to avoid obvious issues.
Completeness checks (what's missing):
Does every REQ-XXX in the system requirements have a corresponding design element?
Could a different team implement this without asking questions?
Are any sections under-specified ("refer to existing implementation" without detail)?
Rigor checks (what's there but shouldn't be trusted):
Pseudo-precise numbers: Every specific number must have a verifiable source. If not, replace with a range or mark [待验证: 无基准数据，需压测确认].
Cross-chapter contradictions: When one inconsistency is found, scan ALL related chapters — a single spotted conflict typically hides a cluster. Fix as a group.
Selection rationale: A comparison table is not enough. Does each criterion have a verifiable basis? Are rejected options explained with specific technical reasons?
Objective chapter naming: Design documents present solutions — they do not self-promote. "独有的设计创新" → restructure as analysis ("领域需求 vs 框架能力差距").
Interface lists without backing: An API list derived from analysis before implementation is a projection, not a design commitment. Label it "初步规划（待实现验证）" and document the architectural principles separately.
The core question for every assertion: "What is the evidence?" — If none, either supply it or label it [待验证].
The Challenger prevents bad decisions during design. The Reviewer catches what's missing and what shouldn't be trusted. Both are mandatory.
Design Judgment vs Assumption
Every design decision is either a locked judgment or an assumption.
Locked Judgment
Backed by one of:
A knowledge base document (verified via team knowledge base)
An explicit statement in the system requirements document
Team standards from rules/ files
User confirmation in this session
Write locked judgments as declarative statements: "The subsystem uses Redis for session storage."
Assumption ([待确认])
A design decision made without explicit backing. Mark these inline:
The cache will hold up to 10000 entries. [待确认: no knowledge base baseline, no historical data found — confirm with user before finalizing DFX section]
Rules:
Never present an assumption as a judgment
Every [待确认] item must be surfaced to the user before the design is marked approved
DFX numbers are almost always assumptions — if no knowledge base value exists and no historical baseline is available, ask the user. Never use template example values as real requirements.
Assumptions about existing system behavior must be verified against code (not just knowledge base)
Incremental Alignment
Design documents are written in layers with user checkpoints — not dumped as a complete draft. Each checkpoint is a natural decision boundary: if something is wrong here, fixing it is cheap. If you skip the checkpoint and write 5 more chapters on a wrong foundation, rework is expensive.
Do NOT write an entire document and then ask for approval at the end. Ask after meaningful chunks.
These are mandatory and must be verified before marking subsystem design as complete:
Red Line 1: Chapter Completeness
No chapter in the design document may be empty. Every chapter must contain substantive content. If a chapter is not applicable, it must explicitly state "Not applicable" with a reason. This rule is stated at the top of the template.
Red Line 2: Reliability Section
The design must include a reliability section covering:
Fault tolerance analysis for the feature's carrier components
Resource usage analysis (no uncontrolled resource consumption)
Business process reliability (each business flow is reliable)
Based on fault-tolerance thinking, not code defect analysis
Red Line 3: Security Section
The design must include a security section covering:
Security baseline mechanism integration
Threat modeling analysis (if required by security manager)
Security design based on identified risks
Pre-use component version compliance and vulnerability status
Mandatory Template Elements
When generating subsystem design documents, the following elements from the template are mandatory and must not be skipped or simplified:
Mermaid Diagrams (marked with star-mandatory in template)
All sections marked ⭐必填 in the template require Mermaid or PlantUML diagrams. ASCII-only diagrams are explicitly forbidden. Each diagram must be followed by a structured text description table.
Subsystem-level design mandatory diagrams:
Section 4.2 -- Internal flow diagrams with sequence diagrams showing both normal and exception branches (alt/else blocks)
SQL DDL for Database Tables
Subsystem-level design Section 4.4.1 requires database tables defined using SQL DDL (not Markdown tables). Each DDL must include:
COMMENT on every column explaining its meaning
Enum fields listing all legal values
Index comments explaining which queries they serve
Table-level comment and associated code repository annotation
AI Readability Annotations
The template contains [AI可读性要求] and [AI读取引导] annotations that define structured output requirements. These must be followed precisely:
Every flow must include both a diagram (for humans) AND a step description table (for AI)
Interface references must use standard format: 接口名 (HTTP方法 路径)，详见《API Schema文档》§X.X.X
Configuration files must specify: storage path, format, field types, defaults, value ranges, and whether restart is required
Document Metadata Table
The template starts with a structured metadata table that must be filled in completely, including: document type, subsystem name, system name, iteration version, input/output documents, code repository, keywords.
DFX Dimensions
Every subsystem design document must address 6 DFX dimensions, each addressing concrete implementation within the subsystem:
Dimension
Template Section
Key Content
安全性 (Security)
7.1
Input validation, sensitive data handling, threat modeling results
可靠性 (Reliability)
7.2
Process/service reliability, data reliability, FMEA analysis
可运维性 (Operability)
7.3
Log design (levels, format, storage), monitoring metrics (Prometheus), deployment operations
可测试性 (Testability)
7.4
Dependency injection, test interfaces
可扩展性 (Scalability)
7.5
Plugin mechanisms, configuration-driven extension
可复用性 (Reusability)
7.6
Reusable modules, design pattern application
Important template rules (apply when writing subsystem-level design):
When a subsystem has more than 3 groups of CRUD interfaces, the document must be split into per-module sub-documents (template Section 4.2 拆分规则)
Flow design sections must NOT include code examples; code examples are only allowed in Section 4.3 (core algorithms and public framework mechanisms)
External calls in step tables must be marked [外部] with DEP-XXX reference numbers matching Section 3.5
Design Review Checklist
The subsystem design must pass these checks organized by template section:
Subsystem responsibilities and boundaries clearly defined (Section 2)
API interface list references OpenAPI definitions, not duplicated (Section 3.1)
External dependency interfaces listed with DEP-XXX numbers and degradation strategies (Section 3.5)
Internal flows have Mermaid sequence diagrams with alt/else exception branches (Section 4.2)
Test scenario coverage verified: every functional flow documents normal path, exception path, and boundary conditions — gaps are explicit design defects (Section 4.2 + Section 5)
Database tables defined using SQL DDL with COMMENTs (Section 4.4.1)
Configuration files specify path, format, field types, defaults, ranges (Section 4.4.3)
Exception scenarios comprehensively listed with recovery strategies (Section 5)
All 6 subsystem DFX dimensions addressed with substantive content (Section 7)
Logging, audit, and permission requirements fully specified (Section 8)
Cross-Chapter Consistency Check
Run after completing the subsystem document draft (checklist step 4). When you find any inconsistency, don't fix it in isolation — scan the full document for the same class of problem.
Check Type
What to Verify
DFX numbers alignment
Values in design DFX chapters must match the system requirements document §4. If they differ, the design must justify the deviation.
Interface reference integrity
Every API reference in subsystem design §3.1 must point to a section that exists in the OpenAPI spec. No orphaned references.
Terminology consistency
Terms defined in §1.2 must be used consistently across all chapters. Check 5-10 key terms.
Risk/dependency completeness
External dependencies in subsystem design §3.5 must appear in the risk analysis. Unanalyzed external dependencies are design gaps.
Quality Checklist
All 3 design red lines pass (no empty chapters, reliability section, security section)
Test scenario coverage complete: every functional flow and exception section covers normal path, exception path, and boundary conditions — any missing scenario type is an explicit gap
All [待确认] items surfaced to user and resolved before marking design approved
ALL 8 sub-documents from the template are present
All ⭐必填 Mermaid diagrams included (not ASCII substitutes), each followed by structured text table
Database tables defined with SQL DDL (not Markdown tables), including COMMENTs and index annotations
AI可读性 annotations followed: flows have both diagrams AND step tables, interfaces use standard reference format
All 6 DFX dimensions addressed with substantive content
Requirements fully traced to design (every requirement has corresponding design anchor)
Risk analysis completed with mitigation plans
External interfaces fully defined with degradation strategies
Next Steps
After quality evaluation passes (grade B or above) and user approves the subsystem design document:
If this was the last subsystem (all subsystems in §2.2 have completed designs): dispatch config.evaluators["doc-quality"] (default: doc-quality-evaluator) using skills/doc-quality-evaluator/agents/evaluator-dispatch-prompt.md for cross-document consistency, then invoke writing-plans
If other subsystems are still pending: remind the user that the remaining subsystem owners should also invoke subsystem-design-spec. Cross-document consistency will run when the last subsystem is complete.
