Back to Details

program-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Program Design

程序设计

Align on code shape before implementation: the types, signatures, call stacks, and file layout that architecture is too coarse for and review is too late to change. The model drafts compact sketches; you argue about taste; then you lock the shape. Nobody writes production code.
This is not an implementation spec. If you are writing function bodies, AC matrices, or a file-by-file work order, you have gone too far.
在实现前就代码形态达成共识：包括架构层面过于粗略、代码评审阶段再修改为时已晚的类型、签名、调用栈和文件布局。由模型生成简洁的草图；团队讨论风格偏好；随后锁定代码形态。此阶段无人编写生产代码。
这不是一份实现规范。如果你正在编写函数体、验收标准（AC）矩阵或逐文件工作指令，那你就做得过头了。

Core contract

核心约定

  • Lock the program for one implementation unit: a ticket, or a capability whose architecture is already settled.
  • Behaviour comes from the spec and ticket. Architecture (if any) constrains seams. This skill owns taste — depth, naming, layout, call shape.
  • Inspect the repository. Prefer evidence over generic best practices.
  • Read-only: inspect code, docs, tests, and history; do not modify production code.
  • Draft sketches, grill taste forks, lock. Stop unless the user asks to continue.
  • Use 
    /codebase-design
    language: module, seam, depth, interface.
  • 针对单个实现单元锁定程序形态：一个工单，或架构已确定的某项功能。
  • 行为逻辑来自需求规格说明书和工单。架构（若存在）约束模块边界。该技能负责把控风格偏好——包括代码深度、命名、布局、调用形态。
  • 检查代码仓库。优先基于实际证据，而非通用最佳实践。
  • 只读操作：检查代码、文档、测试和历史记录；不得修改生产代码。
  • 绘制草图、讨论风格分歧、锁定形态。除非用户要求继续，否则停止操作。
  • 使用
    /codebase-design
    专属术语：module、seam、depth、interface。

When to use / skip

使用/跳过场景

text
wayfinder → grill-with-docs → /to-spec
                 ↓
           /architecture     # system shape, if new seams / multi-ticket
                 ↓
           /program-design   # this skill
                 ↓
           /to-tickets → /implement
SituationSkill
Product or requirements still open
/grilling
/ 
/to-spec
first
New services, schemas, or module boundaries
/architecture
first
Obvious oneshot on an established patternSkip to 
/implement
Architecture is obvious; quality of the code is not
/program-design
Ticket exists and this slice's internals matter
/program-design
 on that ticket
text
wayfinder → grill-with-docs → /to-spec
                 ↓
           /architecture     # system shape, if new seams / multi-ticket
                 ↓
           /program-design   # this skill
                 ↓
           /to-tickets → /implement
场景技能
产品或需求仍未确定先使用
/grilling
/ 
/to-spec
新增服务、schema或模块边界先使用
/architecture
基于已有模式的简单单次任务直接跳至
/implement
架构已明确，但代码质量存疑
/program-design
工单已存在，且该任务的内部实现至关重要针对该工单使用**
/program-design
**

Forbidden

禁止操作

  • Full function bodies
  • Per-AC behaviour matrices
  • Implementation sequences or phased checklists
  • Test-command and fixture inventories
  • Dual representation of the same fact
  • A second evidence appendix restating the sketches
  • Every available visual in one document
  • Box-drawing as the first character, 
    ~
    markers, column-padded comments, unicode 
    ∧ ¬ ∨ ≠
    in sketches
/to-spec
and 
/to-tickets
stay path-free. 
/architecture
stays at module boundaries. 
/implement
owns files, tests, and sequence.
  • 编写完整函数体
  • 按验收标准（AC）制作行为矩阵
  • 制定实现流程或分阶段检查清单
  • 整理测试命令和测试用例清单
  • 同一事实的重复表述
  • 添加复述草图的二次证据附录
  • 在一份文档中塞入所有可用可视化内容
  • 在草图中使用绘图框作为首字符、
    ~
    标记、列对齐注释、unicode符号
    ∧ ¬ ∨ ≠
/to-spec
和
/to-tickets
不涉及具体代码路径。
/architecture
仅关注模块边界。
/implement
负责文件、测试和实现流程。

Steps

操作步骤

1. Establish the unit

1. 确定实现单元

Read the ticket, spec, architecture (if any), ADRs, and project instructions.
Ready when the behaviour is clear and the remaining unknown is how the code should look. If behaviour is still open, stop and send the user back. If a multi-ticket spec is the only input and slice boundaries are unclear, send them to 
/to-tickets
after this — or to 
/architecture
if seams are also unclear.
Record the outcome in one sentence. Recommend defaults for non-blocking ambiguity. Stop for the user only when a taste fork would change public APIs, persistence, security, or system boundaries — those belong in architecture.
This step is complete when the unit and outcome are explicit.
阅读工单、需求规格说明书、架构文档（若有）、架构决策记录（ADRs）和项目说明。
当行为逻辑明确，仅剩余代码形态待确定时，即可进入下一步。若行为逻辑仍未确定，停止操作并引导用户返回前置环节。若仅输入了多工单需求规格说明书，且任务切片边界不清晰，完成此步骤后引导用户使用
/to-tickets
——若模块边界也不清晰，则引导至
/architecture
。
用一句话记录预期结果。对非阻塞性歧义给出默认建议。仅当风格分歧会影响公共API、持久化、安全或系统边界时，才需暂停并等待用户决策——这些内容属于架构范畴。
当实现单元和预期结果明确时，此步骤完成。

2. Inspect the repository

2. 检查代码仓库

Trace the current call path. Note symbols, types, helpers, and conventions this change should reuse. Conflicting patterns: pick one, with evidence.
This step is complete when every proposed seam has an existing counterpart or is named as new and justified.
追踪当前调用路径。记录本次变更应复用的符号、类型、辅助工具和约定。若存在冲突模式，需基于证据选择其一。
当所有提议的模块边界都有现有对应项，或已明确命名为新边界并给出理由时，此步骤完成。

3. Draft the smallest sketches

3. 绘制最简草图

Pick only the views this change needs — usually two, rarely more than three. Follow 
references/program-design-template.md
for rendering, including the sketch formatting rules. Those rules exist because chat highlighters, not the author, control color and wrapping.
Change is aboutView
Where it lives / what is newFile tree in 
diff
— marker, then 
├─
│
└─
Orchestration or control flowCall tree in 
diff
— same glyphs as calldiff
Frontend structureComponent tree in 
diff
Types an agent would get wrongSignatures and types — no bodies
The algorithm is the decisionShort pseudocode
Use 
diff
when the surrounding shape already exists. Show the whole block only when most of it is new.
Prefer, in order:
  1. Existing code over new code.
  2. Local code over a shared abstraction.
  3. Established repository patterns over new patterns.
  4. Explicit code over generic frameworks.
  5. A narrow implementation over speculative extensibility.
  6. One clear execution path over interchangeable layers.
New interfaces, factories, adapters, registries, or shared utilities require a current problem with multiple immediate call sites.
This step is complete when a reviewer can see the proposed program without reading prose around it.
仅选择本次变更所需的视图——通常为2个，最多不超过3个。遵循
references/program-design-template.md
进行绘制，包括草图格式规则。制定这些规则是因为聊天工具的高亮器（而非作者）控制着颜色和换行。
变更关注点视图类型
代码存放位置/新增内容
diff
格式的文件树——标记后使用
├─
│
└─
编排或控制流
diff
格式的调用树——使用与calldiff相同的符号
前端结构
diff
格式的组件树
易被Agent误判的类型签名和类型——不含函数体
算法本身即为决策点简短伪代码
当周边代码形态已存在时，使用
diff
格式。仅当大部分内容为新增时，才展示完整代码块。
优先级顺序如下：
  1. 优先复用现有代码，而非编写新代码。
  2. 优先使用本地代码，而非共享抽象。
  3. 优先遵循仓库已有的模式，而非引入新模式。
  4. 优先使用显式代码，而非通用框架。
  5. 优先实现窄范围功能，而非推测性扩展性。
  6. 优先采用清晰的单一执行路径，而非可互换的多层结构。
新增接口、工厂、适配器、注册器或共享工具，需基于当前存在的多调用场景问题。
当评审人员无需阅读周边文字即可理解提议的程序形态时，此步骤完成。

4. Grill taste

4. 讨论风格分歧

Put the real forks to the user, one at a time, each with a recommendation. A taste fork is something a reviewer would fight about: deep vs shallow module, existing helper vs new file, sync vs job, this seam vs that one.
Revise the sketches after each answer. Do not interview about facts the repo already contains.
This step is complete when remaining forks are locked or explicitly deferred.
将实际存在的风格分歧逐一呈现给用户，并给出建议。风格分歧指评审人员可能争论的点：深层模块 vs 浅层模块、复用现有辅助工具 vs 新增文件、同步执行 vs 异步任务、此模块边界 vs 彼模块边界。
每次得到用户反馈后修改草图。无需询问代码仓库已有的事实信息。
当剩余的风格分歧已解决或明确推迟时，此步骤完成。

5. Lock

5. 锁定形态

Persist only when a later session needs the sketches (
/implement
or 
/to-tickets
in a fresh context). If none exists, use 
docs/agents/program-design/<short-slug>.md
. For small work continuing in this conversation, the sketches in-chat are the artifact.
Before handing off, verify:
  • Two or three sketches, not a spec.
  • File layout and call stacks follow the sketch formatting rules in 
    references/program-design-template.md
    (diff marker then 
    ├─
    │
    └─
    , no 
    ~
    , no padded comment columns, lines ~72 characters, predicates in words).
  • No function bodies, AC matrices, test commands, or implementation sequence.
  • Proposed symbols are marked; existing symbols come from the repo.
  • Taste forks are resolved or named as blocking.
仅当后续环节需要草图时（如新会话中的
/implement
或
/to-tickets
），才持久化存储草图。若无此需求，存储至
docs/agents/program-design/<short-slug>.md
。对于本次会话中持续进行的小型任务，聊天中的草图即为成果物。
移交前需验证：
  • 仅包含2-3个草图，而非规范文档。
  • 文件布局和调用栈遵循
    references/program-design-template.md
    中的草图格式规则（diff标记后使用
    ├─
    │
    └─
    ，无
    ~
    标记，无列对齐注释，每行约72字符，谓词用文字表述）。
  • 无函数体、AC矩阵、测试命令或实现流程。
  • 提议的符号已标记；现有符号均来自代码仓库。
  • 风格分歧已解决或已标记为阻塞项。

Handoff

移交环节

Report:
  1. Path to the document, or 
    in-conversation
    .
  2. One-sentence summary of the locked shape.
  3. Blocking decisions, or 
    None
    .
  4. Confirmation that production code was not modified.
  5. Next step:
If slices are not published:
text
/to-tickets using <program-design-path>
If a ticket already exists:
text
/implement <ticket> using <program-design-path>
报告内容：
  1. 文档路径，或
    in-conversation
    （会话内）。
  2. 锁定形态的一句话总结。
  3. 阻塞性决策，或
    None
    （无）。
  4. 确认未修改生产代码。
  5. 下一步：
若任务切片未发布：
text
/to-tickets using <program-design-path>
若工单已存在：
text
/implement <ticket> using <program-design-path>