design-driven

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design-Driven Development

设计驱动开发

A mini methodology: design/ is the skeleton, code is the muscle. Human shapes the skeleton, agent builds the muscle.

design/ is also the institutional memory that outlives any single agent session. Agents are ephemeral, but the architectural skeleton persists — each new agent reads it, works within its boundaries, and leaves the codebase in a state the next agent can trust.

一种轻量级方法论：design/是架构骨架，代码是业务肌肉。由人类搭建骨架，Agent负责构建肌肉。

design/目录同时也是项目的机构记忆，其生命周期远超单个Agent会话。Agent是临时的，但架构骨架会一直存在——每个新的Agent都会先阅读它，在其界定的范围内工作，并将代码库维护到下一个Agent可信赖的状态。

Commands

命令

When invoked with an argument, dispatch to the corresponding file:

```
/design-driven init
```
→ Read and follow
```
commands/init.md
```
in this skill directory. First-time project configuration (agent configs, hooks, directory structure).
```
/design-driven bootstrap
```
→ Read and follow
```
commands/bootstrap.md
```
in this skill directory. Generate the initial
```
design/
```
directory from an existing codebase.
No argument → Continue with the methodology below (the normal loop).

当携带参数调用时，会跳转到对应文件执行：

```
/design-driven init
```
→ 阅读并遵循该技能目录下的
```
commands/init.md
```
。用于首次项目配置（Agent配置、钩子、目录结构）。
```
/design-driven bootstrap
```
→ 阅读并遵循该技能目录下的
```
commands/bootstrap.md
```
。用于从现有代码库生成初始的
```
design/
```
目录。
无参数 → 遵循下方的方法论流程（常规循环）。

Directory Structure

目录结构

project/
├── design/                                        ← Permanent skeleton
│   ├── DESIGN.md                                  ← System shape
│   ├── DESIGN-<aspect>.md                         ← Complex mechanisms (optional)
│   └── decisions/
│       ├── 001-outbox-over-direct-push.md         ← adopted
│       └── 002-split-memory-tiers.md              ← rejected
│
└── blueprints/                                    ← Implementation records
    ├── add-semantic-memory-search.md              ← done (clean, no TODO)
    └── refactor-agent-delegation.md               ← in-progress (has TODO)

Two directories, clear separation:

design/

is the architect's drawings (system shape, permanent),

blueprints/

is the builder's records (task-level approach, kept for reference).

project/
├── design/                                        ← 永久架构骨架
│   ├── DESIGN.md                                  ← 系统架构
│   ├── DESIGN-<aspect>.md                         ← 复杂机制（可选）
│   └── decisions/
│       ├── 001-outbox-over-direct-push.md         ← 已采纳
│       └── 002-split-memory-tiers.md              ← 已拒绝
│
└── blueprints/                                    ← 实现记录
    ├── add-semantic-memory-search.md              ← 已完成（无TODO）
    └── refactor-agent-delegation.md               ← 进行中（含TODO）

两个目录职责明确：

design/

是架构师的设计图（系统架构，永久保存），

blueprints/

是开发者的工作记录（任务级实现方案，用于参考）。

The Loop

开发循环

Every development task follows one path:

  ┌───────────────────────────────┐
  │  Read design/DESIGN.md        │  ← Always start here
  │  Understand the skeleton      │
  └────────────┬──────────────────┘
               │
       ┌───────▼────────┐
       │ Does this task  │
       │ change the      │
       │ system's shape? │
       └───┬─────────┬───┘
           │         │
          NO        YES
           │         │
           │    ┌────▼───────────────────┐
           │    │ Write proposal in      │
           │    │ design/decisions/      │  ← Context + proposal + alternatives
           │    └────┬───────────────────┘
           │         │
           │    ┌────▼───────────────────┐
           │    │ Human reviews          │  ← Wait. Don't code until approved.
           │    └────┬───────────────────┘
           │         │
           │    ┌────▼───────────────────┐
           │    │ Update design/DESIGN.md│  ← Commit design change separately
           │    └────┬───────────────────┘
           │         │
       ┌───▼─────────▼───┐
       │   Plan           │  ← Draw the blueprint, set up scaffolding
       ├──────────────────┤
       │   Build          │  ← Code freely, track progress on scaffolding
       ├──────────────────┤
       │   Verify         │  ← Check against blueprint, tear down scaffolding
       └──────────────────┘

"Changes the shape" = adding/removing/merging modules, changing how modules connect, altering a key mechanism, introducing a new architectural pattern. If you're unsure, it probably doesn't — just code.

所有开发任务都遵循以下流程：

  ┌───────────────────────────────┐
  │  阅读design/DESIGN.md        │  ← 始终从此处开始
  │  理解架构骨架                │
  └────────────┬──────────────────┘
               │
       ┌───────▼────────┐
       │ 该任务是否会     │
       │ 改变系统架构？   │
       └───┬─────────┬───┘
           │         │
          否        是
           │         │
           │    ┌────▼───────────────────┐
           │    │ 在design/decisions/中  │  ← 包含背景、提案及备选方案
           │    │ 编写提案               │
           │    └────┬───────────────────┘
           │         │
           │    ┌────▼───────────────────┐
           │    │ 等待人工审核           │  ← 审核通过前请勿编码
           │    └────┬───────────────────┘
           │         │
           │    ┌────▼───────────────────┐
           │    │ 更新design/DESIGN.md   │  ← 单独提交设计变更
           │    └────┬───────────────────┘
           │         │
       ┌───▼─────────▼───┐
       │   规划           │  ← 编写蓝图文档，搭建基础框架
       ├──────────────────┤
       │   开发           │  ← 在design/界定范围内自由编码，更新进度标记
       ├──────────────────┤
       │   验证           │  ← 对照蓝图文档检查，移除进度标记
       └──────────────────┘

**“架构变更”**指的是添加/移除/合并模块、修改模块间的连接方式、变更核心机制、引入新的架构模式。若你不确定是否属于架构变更，那大概率不是——直接编码即可。

Implementation: Plan → Build → Verify

实现流程：规划 → 开发 → 验证

Plan — Read design/, understand the task, write a blueprint in

blueprints/<task-name>.md

. Define verification criteria upfront — how will you know this task is done? The TODO section is scaffolding: a progress tracker, not a spec. See

references/templates.md

for the format.

Size tasks to fit within a single session. If a task feels too large to hold in your head at once, split it into smaller blueprints.

Build — Code freely within design/ boundaries, following the blueprint's approach. Check off TODO items as you go. If you discover a better approach mid-build, update the blueprint first, then continue. Update the State section with decisions made and current progress, so work can resume if the session is interrupted.

Verify — Check the implementation against the verification criteria defined in Plan. Then confirm: does it stay within design/ boundaries? Is the scope respected? Once verified, tear down the scaffolding: remove the TODO and State sections, mark status as

done

The blueprint sits between design/ and code in granularity:

design/      "The system has a memory layer with shared facts and 
              per-conversation short-term context"

blueprint    "Add semantic search to memory: integrate embedding model, 
              build index on startup, query during context assembly. 
              Reuse existing IMemoryManager interface."

code         The actual embedder, vector store, query functions, tests

Skip the blueprint for bug fixes, small config changes, or tasks that take less time to do than to plan.

规划 — 阅读design/目录，理解任务需求，在

blueprints/<任务名称>.md

中编写蓝图文档。提前定义验证标准——你如何判断任务已完成？TODO部分是进度追踪标记，而非需求规范。格式可参考

references/templates.md

。

任务规模应控制在单个会话内完成。若任务过大，无法一次性理清，可拆分为多个更小的蓝图文档。

开发 — 在design/界定的范围内自由编码，遵循蓝图文档的实现方案。完成TODO项后及时勾选。若开发过程中发现更优方案，需先更新蓝图文档，再继续编码。更新State部分记录已做决策和当前进度，以便会话中断后可继续工作。

验证 — 对照规划阶段定义的验证标准检查实现结果。随后确认：是否符合design/的边界要求？是否符合任务范围？验证通过后，移除进度标记：删除TODO和State部分，将状态标记为

done

。

蓝图文档的粒度介于design/和代码之间：

design/      “系统包含内存层，具备共享事实数据和会话级短期上下文”

blueprint    “为内存层添加语义搜索：集成嵌入模型，启动时构建索引，上下文组装时查询。复用现有IMemoryManager接口。”

code         实际的嵌入工具、向量存储、查询函数及测试代码

可跳过蓝图文档的场景：Bug修复、小型配置变更，或是完成任务比规划更省时的情况。

Proposals and Decisions

提案与决策

When a task requires changing the system's shape:

Write a proposal in

design/decisions/NNN-title.md

(see

templates.md

for the format)

Wait for the human to review
If adopted: update DESIGN.md, mark proposal adopted, commit both together
If rejected: record why in Outcome, mark rejected
Then implement freely within the (new) boundaries

Adopted proposals update DESIGN.md — the proposal file stays as the reasoning record. Rejected proposals stay too — so the next person with the same idea can see why it was already considered.

当任务需要变更系统架构时：

在

design/decisions/NNN-标题.md

中编写提案（格式参考

templates.md

）

等待人工审核
若通过：更新DESIGN.md，标记提案为已采纳，一并提交变更
若拒绝：在Outcome部分记录原因，标记提案为已拒绝
随后在（新的）架构边界内自由实现

已采纳的提案会更新DESIGN.md——提案文件会保留作为决策依据。已拒绝的提案也会保留——以便后续有相同想法的人了解此前的决策原因。

The 30/70 Principle

30/70原则

The design/ directory captures 30% — the critical skeleton. The agent has 70% freedom.

The 30% (in design/):

Module boundaries — what exists, what each does and doesn't do
Data flow — how information moves through the system
Key mechanisms — patterns that define system behavior
Tradeoffs — choices where you picked A over B, and why

The 70% (agent decides freely):

API design, function signatures, error handling
Data structures, algorithms, file organization
Internal module architecture, naming, patterns

Litmus test: If changing it would change the system's shape, it's the 30%. If it changes behavior within the same shape, it's the 70%.

design/目录承载30%的内容——即关键的架构骨架。Agent拥有70%的自主决策权。

30%的内容（位于design/中）：

模块边界——各模块的职责范围
数据流——信息在系统中的流转方式
核心机制——定义系统行为的架构模式
权衡决策——选择方案A而非B的原因

70%的自主决策（由Agent决定）：

API设计、函数签名、错误处理
数据结构、算法、文件组织
模块内部架构、命名规范、设计模式

**检验标准：**若变更会改变系统的架构形态，则属于30%的范畴；若仅在现有架构形态内改变业务行为，则属于70%的范畴。

Reading an Existing Design

阅读现有设计文档

When design/DESIGN.md already exists, read it before every task. Pay attention to:

Module boundaries — Which module owns the thing you're touching?
"Doesn't do" — Is the task something a module explicitly doesn't do?
Key mechanisms — Does your approach align with established patterns?
Non-goals — Is the feature explicitly out of scope?

If the task fits within boundaries, just implement — no need to explain yourself. If it conflicts, surface the conflict before writing code.

当design/DESIGN.md已存在时，每次任务前都需阅读。重点关注：

模块边界——你要修改的内容属于哪个模块的职责？
“不负责”项——该任务是否是某模块明确不负责的内容？
核心机制——你的实现方案是否符合已有的架构模式？
非目标——该功能是否明确超出了项目范围？

若任务符合边界要求，直接实现即可——无需额外说明。若存在冲突，需在编码前提出冲突问题。

Creating a Design from Scratch

从零开始创建设计文档

When no design/DESIGN.md exists, run

/design-driven bootstrap

to explore the codebase and generate the first version. See

references/templates.md

for the DESIGN.md structure and

references/writing-guide.md

for style guidance.

当design/DESIGN.md不存在时，执行

/design-driven bootstrap

扫描代码库并生成初始版本。DESIGN.md的结构参考

references/templates.md

，写作风格参考

references/writing-guide.md

。

project/ ├── design/ ← Permanent skeleton │ ├── DESIGN.md ← System shape │ ├── DESIGN-<aspect>.md ← Complex mechanisms (optional) │ └── decisions/ │ ├── 001-outbox-over-direct-push.md ← adopted │ └── 002-split-memory-tiers.md ← rejected │ └── blueprints/ ← Implementation records ├── add-semantic-memory-search.md ← done (clean, no TODO) └── refactor-agent-delegation.md ← in-progress (has TODO)

project/ ├── design/ ← 永久架构骨架 │ ├── DESIGN.md ← 系统架构 │ ├── DESIGN-<aspect>.md ← 复杂机制（可选） │ └── decisions/ │ ├── 001-outbox-over-direct-push.md ← 已采纳 │ └── 002-split-memory-tiers.md ← 已拒绝 │ └── blueprints/ ← 实现记录 ├── add-semantic-memory-search.md ← 已完成（无TODO） └── refactor-agent-delegation.md ← 进行中（含TODO）

┌───────────────────────────────┐ │ Read design/DESIGN.md │ ← Always start here │ Understand the skeleton │ └────────────┬──────────────────┘ │ ┌───────▼────────┐ │ Does this task │ │ change the │ │ system's shape? │ └───┬─────────┬───┘ │ │ NO YES │ │ │ ┌────▼───────────────────┐ │ │ Write proposal in │ │ │ design/decisions/ │ ← Context + proposal + alternatives │ └────┬───────────────────┘ │ │ │ ┌────▼───────────────────┐ │ │ Human reviews │ ← Wait. Don't code until approved. │ └────┬───────────────────┘ │ │ │ ┌────▼───────────────────┐ │ │ Update design/DESIGN.md│ ← Commit design change separately │ └────┬───────────────────┘ │ │ ┌───▼─────────▼───┐ │ Plan │ ← Draw the blueprint, set up scaffolding ├──────────────────┤ │ Build │ ← Code freely, track progress on scaffolding ├──────────────────┤ │ Verify │ ← Check against blueprint, tear down scaffolding └──────────────────┘

┌───────────────────────────────┐ │ 阅读design/DESIGN.md │ ← 始终从此处开始 │ 理解架构骨架 │ └────────────┬──────────────────┘ │ ┌───────▼────────┐ │ 该任务是否会 │ │ 改变系统架构？ │ └───┬─────────┬───┘ │ │ 否是 │ │ │ ┌────▼───────────────────┐ │ │ 在design/decisions/中 │ ← 包含背景、提案及备选方案 │ │ 编写提案 │ │ └────┬───────────────────┘ │ │ │ ┌────▼───────────────────┐ │ │ 等待人工审核 │ ← 审核通过前请勿编码 │ └────┬───────────────────┘ │ │ │ ┌────▼───────────────────┐ │ │ 更新design/DESIGN.md │ ← 单独提交设计变更 │ └────┬───────────────────┘ │ │ ┌───▼─────────▼───┐ │ 规划 │ ← 编写蓝图文档，搭建基础框架 ├──────────────────┤ │ 开发 │ ← 在design/界定范围内自由编码，更新进度标记 ├──────────────────┤ │ 验证 │ ← 对照蓝图文档检查，移除进度标记 └──────────────────┘

design/ "The system has a memory layer with shared facts and per-conversation short-term context" blueprint "Add semantic search to memory: integrate embedding model, build index on startup, query during context assembly. Reuse existing IMemoryManager interface." code The actual embedder, vector store, query functions, tests

design/ “系统包含内存层，具备共享事实数据和会话级短期上下文” blueprint “为内存层添加语义搜索：集成嵌入模型，启动时构建索引，上下文组装时查询。复用现有IMemoryManager接口。” code 实际的嵌入工具、向量存储、查询函数及测试代码