writing-design-plans

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing Design Plans

编写设计计划

Overview

概述

Complete the design document by appending validated design from brainstorming to the existing file (created in Phase 3 of starting-a-design-plan) and filling in the Summary and Glossary placeholders.

Core principle: Append body to existing document. Generate Summary and Glossary. Commit for permanence.

Announce at start: "I'm using the writing-design-plans skill to complete the design document."

Context: Design document already exists with Title, Summary placeholder, confirmed Definition of Done, and Glossary placeholder. This skill appends the body and fills in placeholders.

通过将头脑风暴中确定的验证后设计内容追加到现有文件（在启动设计计划的第3阶段创建），并填充“摘要”和“术语表”占位符，完成设计文档。

核心原则： 将主体内容追加到现有文档中，生成摘要和术语表，提交以永久保存。

开始时告知： "我正在使用writing-design-plans技能来完成设计文档。"

背景： 设计文档已存在，包含标题、摘要占位符、已确认的完成定义和术语表占位符。本技能将追加主体内容并填充占位符。

Level of Detail: Design vs Implementation

详细程度：设计 vs 实施

Design plans are directional and archival. They can be checked into git and referenced months later. Other design plans may depend on contracts specified here.

Implementation plans are tactical and just-in-time. They verify current codebase state and generate executable code immediately before execution.

What belongs in design plans:

Include	Exclude
Module and directory structure	Task-level breakdowns
Component names and responsibilities	Implementation code
File paths (from investigation)	Function bodies
Dependencies between components	Step-by-step instructions
"Done when" verification criteria	Test code

Exception: Contracts get full specification. When a component exposes an interface that other systems depend on, specify the contract fully:

API endpoints with request/response shapes
Inter-service interfaces (types, method signatures)
Database schemas that other systems read
Message formats for queues/events

Contracts can include code blocks showing types and interfaces. This is different from implementation code — contracts define boundaries, not behavior.

Example — Contract specification (OK):

typescript

interface TokenService {
  generate(claims: TokenClaims): Promise<string>;
  validate(token: string): Promise<TokenClaims | null>;
}

interface TokenClaims {
  sub: string;      // service identifier
  aud: string[];    // allowed audiences
  exp: number;      // expiration timestamp
}

Example — Implementation code (NOT OK for design plans):

typescript

async function generate(claims: TokenClaims): Promise<string> {
  const payload = { ...claims, iat: Date.now() };
  return jwt.sign(payload, config.secret, { algorithm: 'RS256' });
}

The first defines what the boundary looks like. The second implements behavior — that belongs in implementation plans.

设计计划具有指导性和存档性，可以提交到git中，供数月后参考。其他设计计划可能依赖于此文档中规定的契约。

实施计划具有战术性和及时性，会验证当前代码库状态，并在执行前立即生成可执行代码。

设计计划应包含的内容：

包含内容	排除内容
模块和目录结构	任务级别的细分
组件名称和职责	实现代码
文件路径（来自调研结果）	函数体
组件之间的依赖关系	分步操作说明
“完成标准”验证条件	测试代码

例外情况：契约需要完整规范。当组件暴露其他系统依赖的接口时，需完整规范契约：

包含请求/响应结构的API端点
服务间接口（类型、方法签名）
其他系统会读取的数据库模式
队列/事件的消息格式

契约可以包含展示类型和接口的代码块。这与实现代码不同——契约定义边界，而非行为。

示例——契约规范（合规）：

typescript

interface TokenService {
  generate(claims: TokenClaims): Promise<string>;
  validate(token: string): Promise<TokenClaims | null>;
}

interface TokenClaims {
  sub: string;      // service identifier
  aud: string[];    // allowed audiences
  exp: number;      // expiration timestamp
}

示例——实现代码（设计计划中不合规）：

typescript

async function generate(claims: TokenClaims): Promise<string> {
  const payload = { ...claims, iat: Date.now() };
  return jwt.sign(payload, config.secret, { algorithm: 'RS256' });
}

第一个示例定义了边界的样子，第二个示例实现了具体行为——后者属于实施计划的范畴。

File Location and Naming

文件位置和命名

File location:

docs/design-plans/YYYY-MM-DD-<topic>.md

The file is created by starting-a-design-plan Phase 3. This skill appends to that file.

Expected naming convention:

Good:

docs/design-plans/2025-01-18-oauth2-svc-authn.md

Good:

docs/design-plans/2025-01-18-user-prof-redesign.md

Bad:
```
docs/design-plans/design.md
```
Bad:
```
docs/design-plans/new-feature.md
```

文件位置：

docs/design-plans/YYYY-MM-DD-<topic>.md

该文件由启动设计计划的第3阶段创建，本技能将向其追加内容。

预期命名规范：

规范示例：

docs/design-plans/2025-01-18-oauth2-svc-authn.md

规范示例：

docs/design-plans/2025-01-18-user-prof-redesign.md

不规范示例：
```
docs/design-plans/design.md
```
不规范示例：
```
docs/design-plans/new-feature.md
```

Document Structure

文档结构

The design document already exists from Phase 3 of starting-a-design-plan with this structure:

markdown

undefined

设计文档已存在，来自启动设计计划的第3阶段，结构如下：

markdown

undefined

[Feature Name] Design

[功能名称] 设计

Summary

摘要

Definition of Done

完成定义

[Already written - confirmed in Phase 3]

[已编写完成——在第3阶段确认]

Acceptance Criteria

验收标准

Glossary

术语表


**This skill appends the body sections:**

```markdown


**本技能将追加以下主体章节：**

```markdown

Architecture

架构

[Approach selected in brainstorming Phase 2]

[Key components and how they interact]

[Data flow and system boundaries]

[头脑风暴第2阶段选定的方案]

[核心组件及其交互方式]

[数据流和系统边界]

Existing Patterns

现有模式

[Document codebase patterns discovered by investigator that this design follows]

[If introducing new patterns, explain why and note divergence from existing code]

[If no existing patterns found, state that explicitly]

[记录调研人员发现的、本设计遵循的代码库模式]

[如果引入新模式，说明原因并记录与现有代码的差异]

[如果未发现现有模式，需明确说明]

Implementation Phases

实施阶段

Break implementation into discrete phases (<=8 recommended).

REQUIRED: Wrap each phase in HTML comment markers:

将实施过程划分为独立阶段（建议≤8个）。

要求：将每个阶段包裹在HTML注释标记中：

Phase 1: [Name]

阶段1：[名称]

Goal: What this phase achieves

Components: What gets built/modified (exact paths from investigator)

Dependencies: What must exist first

Done when: How to verify this phase is complete (see Phase Verification below)

目标： 本阶段要达成的成果

组件： 要构建/修改的内容（来自调研的精确路径）

依赖项： 必须先完成的内容

完成标准： 如何验证本阶段已完成（见下文阶段验证）

Phase 2: [Name]

阶段2：[名称]

[Same structure]

...continue for each phase...

Why markers: These enable writing-implementation-plans to parse phases individually, reducing context usage and enabling granular task tracking across compaction boundaries.

[相同结构]

...按此格式继续每个阶段...

标记的作用： 这些标记使writing-implementation-plans技能能够单独解析每个阶段，减少上下文占用，并支持跨压缩边界的细粒度任务跟踪。

Additional Considerations

其他考虑事项

[Error handling, edge cases, future extensibility - only if relevant]

[Don't include hypothetical "nice to have" features]


**Then this skill:**
1. Generates Acceptance Criteria (inline) and gets human validation
2. Generates Summary and Glossary to replace the placeholders

[错误处理、边缘情况、未来扩展性——仅在相关时包含]

[不要包含假设性的“锦上添花”功能]


**之后本技能将：**
1. 生成验收标准（内联）并获取人工验证
2. 生成摘要和术语表以替换占位符

Legibility Header

易读性头部

The first three sections (Summary, Definition of Done, Glossary) form the legibility header. These sections help human reviewers quickly understand what the document is about before diving into technical details.

Definition of Done is already written — it was captured in Phase 3 immediately after user confirmation, preserving full fidelity.

Summary and Glossary are generated AFTER writing the body. This avoids summarizing something that hasn't been written yet and ensures they accurately reflect the full document.

See "After Writing: Generating Summary and Glossary" below for the extraction process.

前三个章节（摘要、完成定义、术语表）构成易读性头部。这些章节帮助人工审阅者在深入技术细节前快速了解文档内容。

完成定义已编写完成——在第3阶段用户确认后立即记录，保留完整准确性。

摘要和术语表在主体内容完成后生成。这样可以避免总结尚未编写的内容，确保它们准确反映整个文档。

下文“编写完成后：生成摘要和术语表”部分介绍提取流程。

Implementation Phases: Critical Requirements

实施阶段：关键要求

YOU MUST break design into discrete, sequential phases.

Each phase should:

Achieve one cohesive goal
Build on previous phases (explicit dependencies)
End with a working build and clear "done" criteria
Use exact file paths and component names from codebase investigation

必须将设计划分为独立的、按顺序的阶段。

每个阶段应：

实现一个连贯的目标
基于前序阶段构建（明确依赖关系）
以可运行的构建结果和清晰的“完成标准”收尾
使用来自代码库调研的精确文件路径和组件名称

Phase Verification

阶段验证

Verification depends on what the phase delivers:

Phase Type	Done When	Examples
Infrastructure/scaffolding	Operational success	Project installs, builds, runs, deploys
Functionality/behavior	Tests pass that verify the ACs this phase covers	Unit tests, integration tests, E2E tests

The rule: If a phase implements functionality, it must include tests that verify the specific acceptance criteria it claims to cover. Tests are a deliverable of the phase, not a separate "testing phase" later.

Tying tests to ACs: A functionality phase lists which ACs it covers (e.g.,

oauth2-svc-authn.AC1.1

oauth2-svc-authn.AC1.3

). The phase is not "done" until tests exist that verify each of those specific cases. This creates traceability: AC → phase → test.

Don't over-engineer infrastructure verification. You don't need unit tests for package.json. "npm install succeeds" is sufficient verification for a dependency setup phase. Infrastructure phases typically don't list ACs—their verification is operational.

Do require tests for functionality. Any code that does something needs tests that prove it does that thing. These tests must map to specific ACs, not just "test the code." If a phase covers

oauth2-svc-authn.AC1.3

("Invalid password returns 401"), a test must verify exactly that.

Tests can evolve. A test written in Phase 2 may be modified in Phase 4 as requirements expand. This is expected. The constraint is that Phase 2 ends with passing tests for the ACs Phase 2 claims to cover.

Structure phases as subcomponents. A phase may contain multiple logical subcomponents. List them at the component level — the implementation plan will break these into tasks.

Good structure (component-level):

<!-- START_PHASE_2 -->

验证方式取决于阶段交付内容：

阶段类型	完成标准	示例
基础设施/脚手架	操作成功	项目安装、构建、运行、部署成功
功能/行为	验证本阶段覆盖的验收标准的测试通过	单元测试、集成测试、端到端测试

规则： 如果阶段实现功能，必须包含验证该阶段声称覆盖的特定验收标准的测试。测试是阶段的交付成果，而非后续单独的“测试阶段”。

测试与验收标准的关联： 功能阶段需列出其覆盖的验收标准（例如：

oauth2-svc-authn.AC1.1

oauth2-svc-authn.AC1.3

）。只有当存在验证这些特定场景的测试时，阶段才算“完成”。这创建了可追溯性：验收标准 → 阶段 → 测试。

测试可以演进： 阶段2编写的测试可能在阶段4中因需求扩展而修改。这是预期情况。约束条件是阶段2结束时，其声称覆盖的验收标准对应的测试必须通过。

阶段结构为组件级： 一个阶段可能包含多个逻辑子组件。在组件级别列出它们——实施计划会将这些分解为任务。

规范结构（组件级）：

<!-- START_PHASE_2 -->

Phase 2: Core Services

阶段2：核心服务

Goal: Token generation and session management

Components:

TokenService in
```
src/services/auth/
```
— generates and validates JWT tokens
SessionManager in
```
src/services/auth/
```
— creates, validates, and invalidates sessions
Types in
```
src/types/auth.ts
```
— TokenClaims, SessionData interfaces

Dependencies: Phase 1 (project setup)

Done when: Token generation/validation works, sessions can be created/invalidated, all tests pass


Bad structure (task-level — this belongs in implementation plans):

Phase 2: Core Services

Task 1: TokenPayload type and TokenConfig
Task 2: TokenService implementation
Task 3: TokenService tests
Task 4: SessionManager implementation
Task 5: SessionManager tests


Design plans describe WHAT gets built. Implementation plans describe HOW to build it step-by-step.

**Phase count:**
- Target: 5-8 phases (sweet spot for planning)
- Maximum: 8 phases (hard limit for writing-plans skill)
- If >8 phases needed: Note that multiple implementation plans will be required

**Why <=8 phases matters:**
- writing-plans skill has hard limit of 8 phases per implementation plan
- Exceeding 8 phases forces user to scope or split
- This is by design to prevent overwhelming implementation plans

**If design needs >8 phases:**

Add note to Additional Considerations:
```markdown

目标： Token生成和会话管理

组件：

```
src/services/auth/
```
中的TokenService —— 生成和验证JWT令牌
```
src/services/auth/
```
中的SessionManager —— 创建、验证和失效会话
```
src/types/auth.ts
```
中的类型 —— TokenClaims、SessionData接口

依赖项： 阶段1（项目设置）

完成标准： Token生成/验证功能正常，会话可创建/失效，所有测试通过


不规范结构（任务级——属于实施计划范畴）：

阶段2：核心服务

任务1：TokenPayload类型和TokenConfig
任务2：TokenService实现
任务3：TokenService测试
任务4：SessionManager实现
任务5：SessionManager测试


设计计划描述**要构建什么**，实施计划描述**如何一步步构建**。

**阶段数量：**
- 目标：5-8个阶段（规划的最佳范围）
- 最大值：8个阶段（writing-plans技能的硬限制）
- 如果需要>8个阶段：需注明需要多个实施计划

**为什么≤8个阶段很重要：**
- writing-plans技能每个实施计划最多支持8个阶段
- 超过8个阶段会迫使用户调整范围或拆分
- 这是有意设计的，以避免实施计划过于复杂

**如果设计需要>8个阶段：**

在“其他考虑事项”中添加说明：
```markdown

Additional Considerations

其他考虑事项

Implementation scoping: This design has [N] phases total. The writing-plans skill limits implementation plans to 8 phases. Consider:

Implementing first 8 phases in initial plan
Creating second implementation plan for remaining phases
Simplifying design to fit within 8 phases

undefined

实施范围： 本设计共有[N]个阶段。writing-plans技能限制每个实施计划最多8个阶段。建议：

在初始计划中实施前8个阶段
为剩余阶段创建第二个实施计划
简化设计以适配8个阶段以内

undefined

Using Codebase Investigation Findings

利用代码库调研结果

Include paths and component descriptions from investigation. Do NOT include implementation details.

Good Phase definitions:

Infrastructure phase example:

markdown

<!-- START_PHASE_1 -->

包含调研得到的路径和组件描述，不要包含实现细节。

规范的阶段定义：

基础设施阶段示例：

markdown

<!-- START_PHASE_1 -->

Phase 1: Project Setup

阶段1：项目设置

Goal: Initialize project structure and dependencies

Components:

```
package.json
```
with auth dependencies (jsonwebtoken, bcrypt)
```
tsconfig.json
```
with strict mode
```
src/index.ts
```
entry point

Dependencies: None (first phase)

Done when:

npm install

succeeds,

npm run build

succeeds


**Functionality phase example:**
```markdown
<!-- START_PHASE_2 -->

目标： 初始化项目结构和依赖项

组件：

包含auth依赖项（jsonwebtoken、bcrypt）的
```
package.json
```
启用严格模式的
```
tsconfig.json
```
入口文件
```
src/index.ts
```

依赖项： 无（第一个阶段）

完成标准：

npm install

成功，

npm run build

成功


**功能阶段示例：**
```markdown
<!-- START_PHASE_2 -->

Phase 2: Token Generation Service

阶段2：Token生成服务

Goal: JWT token generation and validation for service-to-service auth

Components:

TokenService in
```
src/services/auth/
```
— generates signed JWTs, validates signatures and expiration
TokenValidator in
```
src/services/auth/
```
— middleware-friendly validation that returns claims or rejects

Dependencies: Phase 1 (project setup)

Done when: Tokens can be generated, validated, and rejected when invalid/expired


Bad Phase definitions:

**Too vague:**
```markdown

目标： 用于服务间认证的JWT令牌生成和验证

组件：

```
src/services/auth/
```
中的TokenService —— 生成签名JWT令牌，验证签名和过期时间
```
src/services/auth/
```
中的TokenValidator —— 支持中间件的验证器，返回claims或拒绝请求

依赖项： 阶段1（项目设置）

完成标准： 令牌可生成、验证，无效/过期令牌会被拒绝


不规范的阶段定义：

**过于模糊：**
```markdown

Phase 1: Authentication

阶段1：认证

Goal: Add auth stuff Components: Auth files Dependencies: Database maybe


**Too detailed (task-level):**
```markdown

目标： 添加认证相关内容 组件： 认证文件 依赖项： 可能需要数据库


**过于详细（任务级）：**
```markdown

Phase 2: Token Service

阶段2：Token服务

Components:

Create
```
src/types/token.ts
```
with TokenClaims interface
Create
```
src/services/auth/token-service.ts
```
with generate() and validate()

Create

tests/services/auth/token-service.test.ts

Step 1: Write failing test for generate()
Step 2: Implement generate()
Step 3: Write failing test for validate() ...


The second example is doing implementation planning's job. Design plans stay at component level.

组件：

创建
```
src/types/token.ts
```
，包含TokenClaims接口
创建
```
src/services/auth/token-service.ts
```
，实现generate()和validate()

创建

tests/services/auth/token-service.test.ts

步骤1：为generate()编写失败测试
步骤2：实现generate()
步骤3：为validate()编写失败测试 ...


第二个示例属于实施计划的工作，设计计划应停留在组件级别。

Writing Style

写作风格

REQUIRED SUB-SKILL: Use house-style:writing-for-a-technical-audience if available.

Otherwise follow these guidelines:

Be concise:

Remove throat-clearing
State facts directly
Skip obvious explanations

Be specific:

Use exact component names
Reference actual file paths
Include concrete examples

Be honest:

Acknowledge unknowns
State assumptions explicitly
Don't over-promise

Example - Good:

markdown

undefined

必备子技能： 如果可用，使用house-style:writing-for-a-technical-audience技能。

否则遵循以下指南：

简洁：

删除冗余的铺垫内容
直接陈述事实
跳过显而易见的解释

具体：

使用精确的组件名称
引用实际文件路径
包含具体示例

诚实：

承认未知内容
明确陈述假设
不要过度承诺

示例——规范：

markdown

undefined

Architecture

架构

Service-to-service authentication using OAuth2 client credentials flow.

Auth service (

src/services/auth/

) generates and validates JWT tokens. API middleware (

src/api/middleware/auth.ts

) validates tokens on incoming requests. Token store (

src/data/token-store.ts

) maintains revocation list in PostgreSQL.

Tokens expire after 1 hour. Refresh not needed for service accounts (can request new token).


**Example - Bad:**
```markdown

采用OAuth2客户端凭证流程实现服务间认证。

Auth服务（

src/services/auth/

）生成和验证JWT令牌。API中间件（

src/api/middleware/auth.ts

）在请求进入时验证令牌。Token存储（

src/data/token-store.ts

）在PostgreSQL中维护吊销列表。

令牌1小时后过期，服务账户无需刷新（可请求新令牌）。


**示例——不规范：**
```markdown

Architecture

架构

In this exciting new architecture, we'll be implementing a robust and scalable authentication system that leverages the power of OAuth2! The system will be designed with best practices in mind, ensuring security and performance at every level. We'll use industry-standard JWT tokens that provide excellent flexibility and are widely supported across the ecosystem. This will integrate seamlessly with our existing infrastructure and provide a solid foundation for future enhancements!

undefined

在这个令人兴奋的新架构中，我们将利用OAuth2的强大功能实现一个健壮且可扩展的认证系统！系统将遵循最佳实践设计，确保各个层面的安全性和性能。我们将使用行业标准的JWT令牌，提供出色的灵活性，并在生态系统中得到广泛支持。这将与我们现有的基础设施无缝集成，为未来的增强提供坚实的基础！

undefined

Existing Patterns Section

现有模式章节

Purpose: Document what codebase investigation revealed.

Include:

Patterns this design follows from existing code
Why those patterns were chosen (if known)
Any divergence from existing patterns with justification

If following existing patterns:

markdown

undefined

目的： 记录代码库调研的结果。

包含内容：

本设计遵循的现有代码模式
选择这些模式的原因（如果已知）
任何与现有模式的差异及理由

如果遵循现有模式：

markdown

undefined

Existing Patterns

现有模式

Investigation found existing authentication in

src/services/legacy-auth/

. This design follows the same service structure:

Service classes in
```
src/services/<domain>/
```
Middleware in
```
src/api/middleware/
```
Data access in
```
src/data/
```

Token storage follows pattern from

src/data/session-store.ts

(PostgreSQL with TTL).


**If no existing patterns:**
```markdown

调研发现

src/services/legacy-auth/

中存在现有认证实现。本设计遵循相同的服务结构：

服务类位于
```
src/services/<domain>/
```
中间件位于
```
src/api/middleware/
```
数据访问位于
```
src/data/
```

Token存储遵循

src/data/session-store.ts

中的模式（带TTL的PostgreSQL）。


**如果没有现有模式：**
```markdown

Existing Patterns

现有模式

Investigation found no existing authentication implementation. This design introduces new patterns:

Service layer for business logic (
```
src/services/
```
)
Middleware for request interception (
```
src/api/middleware/
```
)

These patterns align with functional core, imperative shell separation.


**If diverging from existing patterns:**
```markdown

调研未发现现有认证实现。本设计引入新模式：

业务逻辑服务层（
```
src/services/
```
）
请求拦截中间件（
```
src/api/middleware/
```
）

这些模式符合“功能核心、命令式外壳”的分离原则。


**如果偏离现有模式：**
```markdown

Existing Patterns

现有模式

Investigation found legacy authentication in

src/auth/

. This design diverges:

OLD: Monolithic
```
src/auth/auth.js
```
(600 lines, mixed concerns)
NEW: Separate services (
```
token-service.ts
```
,
```
validator.ts
```
) following FCIS

Divergence justified by: Legacy code violates FCIS pattern, difficult to test, high coupling.

undefined

调研发现

src/auth/

中存在遗留认证实现。本设计与之不同：

旧模式：单体式
```
src/auth/auth.js
```
（600行，混合关注点）
新模式：遵循FCIS原则的独立服务（
```
token-service.ts
```
、
```
validator.ts
```
）

偏离理由：遗留代码违反FCIS模式，难以测试，耦合度高。

undefined

Additional Considerations

其他考虑事项

Only include if genuinely relevant:

Error handling - if not obvious:

markdown

undefined

仅在真正相关时包含：

错误处理——如果不明显：

markdown

undefined

Additional Considerations

其他考虑事项

Error handling: Token validation failures return 401 with generic message (don't leak token details). Service-to-service communication failures retry 3x with exponential backoff before returning 503.


**Edge cases** - if non-obvious:
```markdown
**Edge cases:** Clock skew handled by 5-minute token validation window. Revoked tokens remain in database for 7 days for audit trail.

Future extensibility - if architectural decision enables future features:

markdown

**Future extensibility:** Token claims structure supports adding user metadata (currently unused). Enables future human user authentication without architecture change.

Do NOT include:

"Nice to have" features not in current design
Hypothetical future requirements
Generic platitudes ("should be secure", "needs good testing")

错误处理： Token验证失败时返回401和通用消息（不泄露Token细节）。服务间通信失败时重试3次，使用指数退避策略，之后返回503。


**边缘情况**——如果非显而易见：
```markdown
**边缘情况：** 通过5分钟的Token验证窗口处理时钟偏差。已吊销的令牌在数据库中保留7天用于审计追踪。

未来扩展性——如果架构决策支持未来功能：

markdown

**未来扩展性：** Token claims结构支持添加用户元数据（当前未使用）。无需更改架构即可支持未来的人类用户认证。

不要包含：

当前设计中没有的“锦上添花”功能
假设性的未来需求
通用陈词滥调（如“应保证安全”、“需要良好测试”）

After Body: Generating and Validating Acceptance Criteria

主体内容完成后：生成并验证验收标准

After appending the body, generate Acceptance Criteria and get human validation BEFORE Summary/Glossary.

Acceptance Criteria translate the Definition of Done into specific, verifiable items that become the basis for test requirements during implementation. You have full context from just writing the phases—do this inline, no subagent needed.

追加主体内容后，在生成摘要/术语表之前，生成验收标准并获取人工验证。

验收标准将完成定义转化为具体的、可验证的条目，成为实施阶段测试需求的基础。此时你已具备编写阶段的完整上下文，直接内联生成即可，无需子代理。

What Acceptance Criteria Must Cover

验收标准必须覆盖的内容

For each Definition of Done item, think through:

Success cases: What are all the ways this can succeed? List each distinctly.
- Happy path: the normal, expected flow
- Variations: different valid inputs, configurations, user types
- Edge cases: boundary values, empty inputs, maximum sizes
Important failure cases: What should the system reject or handle gracefully?
- Invalid inputs (malformed, out of range, wrong type)
- Unauthorized access attempts
- Resource exhaustion or unavailability
- Concurrent access conflicts

Then look at the Implementation Phases and brainstorming details for additional cases:

Integration points between phases (data flows correctly between components)
Behavior implied by architectural decisions (caching, retries, timeouts)
Edge cases surfaced during design discussion

针对每个完成定义条目，思考：

成功场景： 所有可能成功的情况？分别列出。
- 正常路径：常规、预期的流程
- 变体：不同的有效输入、配置、用户类型
- 边缘情况：边界值、空输入、最大尺寸
重要失败场景： 系统应拒绝或优雅处理的情况？
- 无效输入（格式错误、超出范围、类型错误）
- 未授权的访问尝试
- 资源耗尽或不可用
- 并发访问冲突

然后查看实施阶段和头脑风暴细节，寻找其他情况：

阶段之间的集成点（组件间数据流正确）
架构决策隐含的行为（缓存、重试、超时）
设计讨论中提出的边缘情况

Writing Criteria

编写标准

Each criterion must be observable and testable:

Good: "API returns 401 when token is expired" Good: "User sees error message when password is less than 8 characters" Good: "System processes 100 concurrent requests within 2 seconds"

Bad: "System is secure" (vague) Bad: "Code is clean" (subjective) Bad: "Performance is acceptable" (unmeasurable)

每个标准必须可观察、可测试：

规范： "API在令牌过期时返回401" 规范： "当密码长度小于8个字符时，用户会看到错误消息" 规范： "系统在2秒内处理100个并发请求"

不规范： "系统是安全的"（模糊） 不规范： "代码整洁"（主观） 不规范： "性能可接受"（无法衡量）

Structure

结构

Scoped AC format:

{slug}.AC{N}.{M}

where

{slug}

is extracted from the design plan filename (everything after

YYYY-MM-DD-

, excluding

.md

For design plan

2025-01-18-oauth2-svc-authn.md

, the slug is

oauth2-svc-authn

. All AC identifiers use this prefix:

markdown

undefined

带范围的AC格式：

{slug}.AC{N}.{M}

，其中

{slug}

从设计计划文件名中提取（

YYYY-MM-DD-

之后、

.md

之前的部分）。

对于设计计划

2025-01-18-oauth2-svc-authn.md

，slug为

oauth2-svc-authn

。所有AC标识符使用该前缀：

markdown

undefined

Acceptance Criteria

验收标准

oauth2-svc-authn.AC1: Users can authenticate

oauth2-svc-authn.AC1：用户可完成认证

oauth2-svc-authn.AC1.1 Success: User with valid credentials receives auth token
oauth2-svc-authn.AC1.2 Success: Token contains correct user ID and permissions
oauth2-svc-authn.AC1.3 Failure: Invalid password returns 401 with generic error (no password hint)
oauth2-svc-authn.AC1.4 Failure: Locked account returns 403 with lockout duration
oauth2-svc-authn.AC1.5 Edge: Empty password field shows validation error before submission

oauth2-svc-authn.AC1.1 成功： 凭证有效的用户获取到认证令牌
oauth2-svc-authn.AC1.2 成功： 令牌包含正确的用户ID和权限
oauth2-svc-authn.AC1.3 失败： 密码无效时返回401和通用错误（不提示密码相关信息）
oauth2-svc-authn.AC1.4 失败： 账户锁定时返回403和锁定时长
oauth2-svc-authn.AC1.5 边缘情况： 密码字段为空时，提交前显示验证错误

oauth2-svc-authn.AC2: Sessions persist across page refresh

oauth2-svc-authn.AC2：会话在页面刷新后保持

oauth2-svc-authn.AC2.1 Success: ...
oauth2-svc-authn.AC2.2 Failure: ... ...

oauth2-svc-authn.AC2.1 成功： ...
oauth2-svc-authn.AC2.2 失败： ... ...

oauth2-svc-authn.AC[N]: Cross-Cutting Behaviors

oauth2-svc-authn.AC[N]：跨领域行为

oauth2-svc-authn.AC[N].1: Token expiration triggers re-authentication prompt (not silent failure)
oauth2-svc-authn.AC[N].2: All API errors include correlation ID for debugging
...


**Why scoped:** Multiple plan-and-execute rounds accumulate tests in the same codebase. Scoped identifiers prevent collision—`oauth2-svc-authn.AC2.1` and `user-prof.AC2.1` are unambiguous. Implementation phases, task specs, and test names all use the full scoped identifier.

oauth2-svc-authn.AC[N].1： 令牌过期触发重新认证提示（而非静默失败）
oauth2-svc-authn.AC[N].2： 所有API错误包含调试用的关联ID
...


**带范围的原因：** 多轮规划与执行会在同一代码库中积累测试。带范围的标识符避免冲突——`oauth2-svc-authn.AC2.1`和`user-prof.AC2.1`不会混淆。实施阶段、任务规范和测试名称均使用完整的带范围标识符。

Validation

验证

Present generated criteria to the user. Use AskUserQuestion: "Review the acceptance criteria. Approve to continue, or describe what's missing or needs revision."

Loop until approved. Then replace the placeholder in the document and proceed to Summary/Glossary.

将生成的标准呈现给用户，使用AskUserQuestion："请审阅验收标准。确认通过以继续，或描述缺失或需要修改的内容。"

循环直到通过，然后替换文档中的占位符，继续生成摘要/术语表。

After Writing: Generating Summary and Glossary

编写完成后：生成摘要和术语表

After appending the body (Architecture through Additional Considerations), generate Summary and Glossary using a subagent with fresh context.

Why a subagent?

Fresh context avoids "context rot" from the long brainstorming/writing session
Acts as a forcing function: if the subagent can't extract a coherent summary, the document is unclear
Mirrors the experience of a human reviewer seeing the document for the first time

Step 1: At this point the document looks like:

The body has been appended and Acceptance Criteria validated:

markdown

undefined

追加主体内容（架构至其他考虑事项）后，使用具有全新上下文的子代理生成摘要和术语表。

为什么使用子代理？

全新上下文避免长时间头脑风暴/编写会话中的“上下文衰减”
起到强制约束作用：如果子代理无法提取连贯的摘要，说明文档不够清晰
模拟人工审阅者首次查看文档的体验

步骤1：此时文档结构如下：

主体内容已追加，验收标准已验证：

markdown

undefined

[Feature Name] Design

[功能名称] 设计

Summary

摘要

Definition of Done

完成定义

[Already written from Phase 3]

[来自第3阶段的已编写内容]

Acceptance Criteria

验收标准

[Validated in previous step]

[上一步验证完成]

Glossary

术语表

Architecture

架构

[... body content ...]

[...主体内容...]

Existing Patterns

现有模式

[... body content ...]

[...主体内容...]

Implementation Phases

实施阶段

[... body content ...]

[...主体内容...]

Additional Considerations

其他考虑事项

[... body content ...]


**Step 2: Dispatch extraction subagent**

Use the Task tool to generate Summary and Glossary:

<invoke name="Task"> <parameter name="subagent_type">ed3d-basic-agents:sonnet-general-purpose</parameter> <parameter name="description">Generating Summary and Glossary for design document</parameter> <parameter name="prompt"> Read the design document at [file path].

Generate two sections to replace the placeholders in the document:

Summary: Write 1-2 paragraphs summarizing what is being built and the high-level approach. This should be understandable to someone unfamiliar with the codebase. The Definition of Done section already exists — your summary should complement it by explaining the "how" rather than restating the "what."
Glossary: List domain terms from the application and third-party concepts (libraries, frameworks, patterns) that a reviewer needs to understand this document. Format as:
- [Term]: [Brief explanation]
Include only terms that appear in the document and would benefit from explanation.
Omitted Terms: List terms you considered but skipped as too obvious or generic. Only include borderline cases — terms that a less technical reviewer might not know. Format as a simple comma-separated list.

Return all three sections. The first two are markdown ready to insert; the third is for transparency about what was excluded. </parameter> </invoke>


**Step 3: Review omitted terms with user**

Before inserting the extracted sections, briefly mention the omitted terms to the user:

"Glossary includes [X terms]. Omitted as likely obvious: [list from subagent]. Let me know if any of those should be included."

Don't wait for approval — proceed to insert the sections. The user can hit escape and ask for adjustments if needed.

**Step 4: Replace placeholders**

Replace the Summary and Glossary placeholder comments with the subagent's output. Do not insert the Omitted Terms section — that was for your transparency message only.

**Step 5: Review and adjust**

Briefly review the generated sections for accuracy. The subagent may miss nuance from the conversation — adjust if needed, but prefer the subagent's version when it's accurate (it reflects what the document actually says, not what you remember).

[...主体内容...]


**步骤2：调度提取子代理**

使用Task工具生成摘要和术语表：

<invoke name="Task"> <parameter name="subagent_type">ed3d-basic-agents:sonnet-general-purpose</parameter> <parameter name="description">为设计文档生成摘要和术语表</parameter> <parameter name="prompt"> 读取位于[文件路径]的设计文档。

生成两个章节以替换文档中的占位符：

摘要： 撰写1-2段内容，总结要构建的内容和高层方案。内容应让不熟悉代码库的人也能理解。完成定义章节已存在——你的摘要应补充说明“如何实现”，而非重复“要实现什么”。
术语表： 列出文档中出现的领域术语和第三方概念（库、框架、模式），帮助审阅者理解文档。格式为：
- [术语]：[简要解释]
仅包含文档中出现的、需要解释的术语。
省略的术语： 列出你考虑过但因过于明显或通用而跳过的术语。仅包含边缘情况——技术水平较低的审阅者可能不知道的术语。格式为简单的逗号分隔列表。

返回所有三个章节。前两个是可直接插入的markdown格式；第三个用于说明省略的原因，增加透明度。 </parameter> </invoke>


**步骤3：与用户确认省略的术语**

在插入提取的章节前，向用户简要提及省略的术语：

"术语表包含[X个术语]。因认为过于明显而省略的术语：[子代理提供的列表]。如果其中有需要包含的，请告知我。"

无需等待确认，继续插入章节。如果需要调整，用户可中断并提出修改请求。

**步骤4：替换占位符**

将摘要和术语表的占位符注释替换为子代理的输出。不要插入“省略的术语”章节——该部分仅用于你的透明度说明。

**步骤5：审阅和调整**

简要审阅生成的章节以确保准确性。子代理可能会遗漏对话中的细微差别——如有需要可调整，但在准确的情况下优先使用子代理的版本（它反映了文档实际内容，而非你的记忆）。

After Summary and Glossary: Commit

摘要和术语表完成后：提交

Commit the design document:

bash

git add docs/design-plans/YYYY-MM-DD-<topic>.md
git commit -m "$(cat <<'EOF'
docs: add [feature name] design plan

Completed brainstorming session. Design includes:
- [Key architectural decision 1]
- [Key architectural decision 2]
- [N] implementation phases
EOF
)"

Announce completion:

"Design plan documented in

docs/design-plans/YYYY-MM-DD-<topic>.md

and committed."

提交设计文档：

bash

git add docs/design-plans/YYYY-MM-DD-<topic>.md
git commit -m "$(cat <<'EOF'
docs: add [feature name] design plan

Completed brainstorming session. Design includes:
- [Key architectural decision 1]
- [Key architectural decision 2]
- [N] implementation phases
EOF
)"

告知完成：

"设计计划已记录在

docs/design-plans/YYYY-MM-DD-<topic>.md

并提交。"

Common Rationalizations - STOP

常见自我合理化——停止

Excuse	Reality
"I'll write the summary first since I know what I'm building"	Write body first. Summarize what you wrote, not what you planned.
"I can write Summary and Glossary myself, don't need subagent"	Subagent has fresh context and acts as forcing function. Use it.
"Glossary isn't needed, terms are obvious"	Obvious to you after brainstorming. Not to fresh reviewer. Include it.
"Design is simple, don't need phases"	Phases make implementation manageable. Always include.
"Phases are obvious, don't need detail"	writing-plans needs component descriptions. Provide them.
"Can have 10 phases if needed"	Hard limit is 8. Scope or split.
"I'll include the code so implementation is easier"	No. Implementation plans generate code fresh from codebase state. Design provides direction only.
"Breaking into tasks helps the reader"	Task breakdown is implementation planning's job. Design stays at component level.
"I'll just show how the function works"	Implementation code doesn't belong in design. Show contracts/interfaces if needed, not function bodies.
"Additional considerations should be comprehensive"	Only include if relevant. YAGNI applies.
"Should document all future possibilities"	Document current design only. No hypotheticals.
"Existing patterns section can be skipped"	Shows investigation happened. Always include.
"Can use generic file paths"	Exact paths from investigation. No handwaving.
"Tests can be a separate phase at the end"	No. Tests for functionality belong in the phase that creates that functionality.
"We'll add tests after the code works"	Phase isn't done until its tests pass. Tests are deliverables, not afterthoughts.
"Infrastructure needs unit tests too"	No. Infrastructure verified operationally. Don't over-engineer.
"Phase 3 tests will cover Phase 2 code"	Each phase tests its own deliverables. Later phases may extend tests, but don't defer.
"Phase markers are just noise"	Markers enable granular parsing. Implementation planning depends on them. Always include.
"Acceptance criteria are just the Definition of Done restated"	Criteria must be specific and verifiable. "System is secure" becomes "API rejects invalid tokens with 401."
"User approved DoD, don't need to validate criteria"	Criteria translate DoD into testable items. User must confirm this translation is correct.
"I'll skip criteria validation to save time"	Implementation planning depends on validated criteria. Skipping creates downstream confusion.
"Criteria are obvious from the phases"	Obvious to you. User must confirm they agree on what 'done' means before proceeding.

All of these mean: STOP. Follow the structure exactly.

借口	实际情况
"我先写摘要，因为我知道要构建什么"	先写主体内容，总结你实际编写的内容，而非计划的内容。
"我自己可以写摘要和术语表，不需要子代理"	子代理具有全新上下文，起到强制约束作用。请使用它。
"术语表不需要，术语都很明显"	头脑风暴后对你来说明显，但对新审阅者不然。请包含术语表。
"设计很简单，不需要阶段划分"	阶段划分使实施更易于管理。始终包含阶段。
"阶段很明显，不需要详细说明"	writing-plans技能需要组件描述。请提供详细信息。
"需要的话可以有10个阶段"	硬限制是8个阶段。调整范围或拆分。
"我包含代码会让实施更容易"	不行。实施计划会根据代码库状态重新生成代码。设计仅提供方向。
"拆分成任务有助于读者理解"	任务拆分是实施计划的工作。设计停留在组件级别。
"我展示函数的工作方式"	实现代码不属于设计范畴。如有需要，展示契约/接口，而非函数体。
"其他考虑事项应全面"	仅包含相关内容。YAGNI原则适用。
"应记录所有未来可能性"	仅记录当前设计。不要包含假设内容。
"现有模式章节可以跳过"	该章节证明已完成调研。始终包含。
"可以使用通用文件路径"	使用调研得到的精确路径。不要含糊其辞。
"测试可以放在最后单独的阶段"	不行。功能对应的测试属于构建该功能的阶段。
"代码运行后再添加测试"	阶段完成的标准是测试通过。测试是交付成果，而非事后补充。
"基础设施也需要单元测试"	不需要。基础设施通过操作验证。不要过度设计。
"阶段3的测试会覆盖阶段2的代码"	每个阶段测试自己的交付成果。后续阶段可能扩展测试，但不要延迟。
"阶段标记只是噪音"	标记支持细粒度解析。实施计划依赖这些标记。始终包含。
"验收标准只是完成定义的重述"	标准必须具体、可验证。“系统是安全的”要转化为“API拒绝无效令牌并返回401”。
"用户已确认完成定义，不需要验证标准"	标准将完成定义转化为可测试的条目。用户必须确认该转化是正确的。
"我跳过标准验证以节省时间"	实施计划依赖已验证的标准。跳过会导致后续混淆。
"阶段中已明确包含标准"	对你来说明显，但用户必须确认他们对“完成”的理解一致，然后再继续。

所有这些借口都意味着：停止。严格遵循结构。

Integration with Workflow

与工作流的集成

This skill completes the design document started in Phase 3:

Phase 3 (Definition of Done) completes
  -> User confirms Definition of Done
  -> File created with Title, Summary placeholder, DoD, AC placeholder, Glossary placeholder
  -> DoD captured at full fidelity

Brainstorming (Phase 4) completes
  -> Validated design exists in conversation
  -> User approved incrementally

Writing Design Plans (this skill)
  -> Append body: Architecture, Existing Patterns, Implementation Phases, Additional Considerations
  -> Add exact paths from investigation
  -> Create discrete phases (<=8)
  -> Generate Acceptance Criteria inline (success + failure cases for each DoD item)
  -> USER VALIDATES Acceptance Criteria
  -> Replace AC placeholder with validated criteria
  -> Dispatch subagent to generate Summary and Glossary
  -> Replace Summary/Glossary placeholders with generated content
  -> Commit to git

Writing Implementation Plans (next step)
  -> Reads this design document
  -> Uses phases as basis for detailed tasks
  -> Uses Acceptance Criteria to generate test-requirements.md
  -> Expects exact paths and structure

Purpose: Create contract between design and implementation. Writing-plans relies on this structure. The legibility header (Summary, DoD, Acceptance Criteria, Glossary) ensures human reviewers can quickly understand the document. Acceptance Criteria provide traceability for test requirements.

本技能完成第3阶段启动的设计文档：

第3阶段（完成定义）完成
  -> 用户确认完成定义
  -> 创建包含标题、摘要占位符、完成定义、验收标准占位符、术语表占位符的文件
  -> 完整记录完成定义

头脑风暴（第4阶段）完成
  -> 对话中存在已验证的设计
  -> 用户已逐步确认

编写设计计划（本技能）
  -> 追加主体内容：架构、现有模式、实施阶段、其他考虑事项
  -> 添加来自调研的精确路径
  -> 划分独立阶段（≤8个）
  -> 内联生成验收标准（每个完成定义条目的成功+失败场景）
  -> 用户验证验收标准
  -> 用已验证的标准替换占位符
  -> 调度子代理生成摘要和术语表
  -> 用生成的内容替换摘要/术语表占位符
  -> 提交到git

编写实施计划（下一步）
  -> 读取本设计文档
  -> 以阶段为基础生成详细任务
  -> 用验收标准生成test-requirements.md
  -> 依赖精确的路径和结构

目的： 在设计和实施之间创建契约。writing-plans技能依赖此结构。易读性头部（摘要、完成定义、验收标准、术语表）确保人工审阅者能快速理解文档。验收标准为测试需求提供可追溯性。