code-docs-spec

Design Document Specifications

This skill provides four sets of specifications, covering the main document types for software design:

1. Product Blueprint (blueprint-spec.md) — the reason for the product's existence, core proposition, value boundaries, and long-term evolution direction
2. Architecture Design Document (architecture-spec.md) — system architecture, module boundaries, interface contracts, and technical decisions
3. Product Requirements Specification (prd-spec.md) — user-visible functionality, acceptance criteria, scope definition, and non-functional requirements
4. Test Specification (test-spec.md) — test strategy, test boundaries, and test cases

It also provides a general pre-delivery quality gate:

• Document Review and Polish (docs-review-spec.md) — compliance checks, structural optimization, language polishing, and pre-delivery confirmation after the first draft is completed

---

Usage Process

Step 1: Determine the document type

变更涉及...
├── 文档审校/润色/合规检查 → docs-review-spec + 对应文档规范
├── 产品定位/核心命题/长期方向 → blueprint-spec
├── 架构/接口/技术决策 → architecture-spec
├── 用户可见功能/需求范围 → prd-spec
└── 测试策略/测试边界/测试用例 → test-spec

Step 2: Read the corresponding specification file

• Product Blueprint → references/blueprint-spec.md
• Architecture Design → references/architecture-spec.md
• Product Requirements → references/prd-spec.md
• Test Specification → references/test-spec.md
• Document Review and Polish → references/docs-review-spec.md

Step 3: Perform the workflow operations according to the Agent in the specification

Each set of specifications includes: trigger condition determination → document structure → writing rules → self-check checklist.

Step 4: Execute the pre-delivery quality gate after the first draft is completed

• After the Agent finishes writing any design document for the first time,REQUIRED read references/docs-review-spec.md
• According to docs-review-spec complete compliance checks and polishing optimization
• Only after passing the original document type's self-check checklist and docs-review-spec can it be delivered or draft mark as active

---

Common Conventions

Rule strength markers(unified across the four sets of specifications):

• REQUIRED — must comply
• PROHIBITED — explicitly prohibited
• OPTIONAL — use as appropriate

Document status labeling(unified format for all design documents):

> **Status**: `draft` | `active`

Move deprecated documents to the deprecated/ folder, and add to the document header > **Superseded by**: [链接]。

Status transition rules:

• draft → active: Mark after the corresponding specification's self-check checklist and docs-review-spec all pass
• Deprecated documents: if there is a replacement document, move them to the deprecated/ folder; if there is no replacement document, delete them directly

Directory Structure：

docs/
├── blueprint/
│   ├── 00-overview.md
│   ├── NN-product-area.md
│   ├── deprecated/
│   └── reference/
├── architecture/
│   ├── 00-overview.md
│   ├── NN-module.md
│   ├── NN.MM-sub-module.md
│   ├── deprecated/
│   └── reference/
├── prd/
│   ├── 00-overview.md
│   ├── NN-feature.md
│   ├── NN.MM-sub-feature.md
│   ├── deprecated/
│   └── reference/
└── test/
    ├── 00-overview.md
    ├── 10-plan-system.md
    ├── 20-cases-module.md
    ├── deprecated/
    └── reference/

PROHIBITED the following practices:

• Skipping trigger condition determination (writing documents for changes that do not require documents)
• Ignoring the self-check checklist (delivering without checking)
• Using vague language ("possibly", "probably", "depending on the situation")
• Copying content from other documents (links should be used instead)