trellis-update-spec

更新代码规范——记录可执行契约

当你学到有价值的内容时（来自调试、实现或讨论），请据此更新相关的代码规范文档。

时机：完成任务、修复错误或发现新模式后

---

代码规范优先规则（关键）

在本项目中，实现工作所说的“规范”指的是代码规范：

• 可执行契约（而非仅阐述原则的文本）
• 具体的签名、载荷字段、环境变量键和边界行为
• 可测试的校验／错误行为

如果变更涉及基础设施或跨层契约，则必须达到代码规范的详细程度。

强制触发条件

变更包含以下任一内容时，必须采用代码规范的详细程度：

• 新增或变更命令或 API 签名
• 跨层请求／响应契约变更
• 数据库架构／迁移变更
• 基础设施集成（存储、队列、缓存、密钥、环境变量接线）

强制输出（7 个部分）

对于触发上述条件的任务，必须包含以下所有部分：

1. 范围／触发条件
2. 签名（命令／API／数据库）
3. 契约（请求／响应／环境变量）
4. 校验与错误矩阵
5. 正常／边界／异常情况
6. 必需的测试（含断言点）
7. 错误做法与正确做法（至少一组对比）

---

何时更新代码规范

触发条件	示例	目标规范
实现了功能	新增了集成或模块	相关规范文件
作出了设计决策	选择可扩展模式而非简单方案	相关规范 +“设计决策”部分
修复了错误	发现错误处理中的隐蔽问题	相关规范（例如错误处理文档）
发现了模式	找到了更好的代码组织方式	相关规范文件
遇到了陷阱	了解到必须先做 X 再做 Y	相关规范 +“常见错误”部分
确立了约定	团队就命名模式达成一致	质量指南
新的思考触发条件	“执行 Y 前别忘了检查 X”	guides/*.md（作为检查清单项）

关键要点：代码规范更新不只是针对问题。每次功能实现都包含设计决策和契约，而未来的 AI／开发者需要据此安全地执行操作。

---

规范结构概览

.trellis/spec/
├── <layer>/           # Per-layer coding standards (e.g., backend/, frontend/, api/)
│   ├── index.md       # Overview and links
│   └── *.md           # Topic-specific guidelines
└── guides/            # Thinking checklists (NOT coding specs!)
    ├── index.md       # Guide index
    └── *.md           # Topic-specific guides

关键：区分代码规范与指南

类型	位置	目的	内容风格
代码规范	<layer>/*.md	告诉 AI“如何安全地实现”	签名、契约、矩阵、情况、测试点
指南	guides/*.md	帮助 AI“思考哪些问题”	检查清单、问题、规范链接

判断规则：问问自己：

• “这是编写代码的方法” → 放入某个层的规范目录
• “这是编写代码前要考虑的内容” → 放入 guides/

示例：

经验	错误位置	正确位置
“此任务应使用 API X，而不是 API Y”	❌ guides/（对思考指南而言过于具体）	✅ 相关规范文件（具体约定）
“执行 Y 时记得检查 X”	❌ 规范文件（对规范而言过于抽象）	✅ guides/（思考检查清单）

指南应是简短、指向规范的检查清单，而不是重复详细规则。

---

更新流程

第 1 步：确认你学到了什么

回答以下问题：

1. 你学到了什么？（请具体说明）
2. 为什么重要？（它能避免什么问题？）
3. 应该放在哪里？（哪个规范文件？）

步骤 2：对更新类型进行分类

类型	描述	操作
设计决策	为什么我们选择方案 X 而非 Y	添加到“设计决策”部分
项目约定	本项目中如何执行某项操作	添加到相关部分并附上示例
新模式	发现的可复用方案	添加到“模式”部分
禁止模式	会导致问题的做法	添加到“反模式”或“禁止事项”部分
常见错误	容易犯的错误	添加到“常见错误”部分
约定	达成一致的标准	添加到相关部分
易忽略的问题	不明显的行为	添加警告提示

步骤 3：阅读目标代码规范

编辑前，请阅读当前代码规范，以便：

• 了解现有结构
• 避免重复内容
• 找到适合添加更新的部分

cat .trellis/spec/<category>/<file>.md

步骤 4：进行更新

遵循以下原则：

1. 具体明确：提供具体示例，而不只是抽象规则
2. 解释原因：说明这能避免什么问题
3. 展示约定：添加签名、载荷字段和错误行为
4. 展示代码：为关键模式添加代码片段
5. 保持简洁：每个部分只讲一个概念

步骤 5：更新索引（如有需要）

如果添加了新部分或代码规范的状态发生了变化，请更新该类别的 index.md。

---

更新模板

基础设施/跨层工作必用模板

## Scenario: <name>

### 1. Scope / Trigger
- Trigger: <why this requires code-spec depth>

### 2. Signatures
- Backend command/API/DB signature(s)

### 3. Contracts
- Request fields (name, type, constraints)
- Response fields (name, type, constraints)
- Environment keys (required/optional)

### 4. Validation & Error Matrix
- <condition> -> <error>

### 5. Good/Base/Bad Cases
- Good: ...
- Base: ...
- Bad: ...

### 6. Tests Required
- Unit/Integration/E2E with assertion points

### 7. Wrong vs Correct
#### Wrong
...
#### Correct
...

添加设计决策

### Design Decision: [Decision Name]

**Context**: What problem were we solving?

**Options Considered**:
1. Option A - brief description
2. Option B - brief description

**Decision**: We chose Option X because...

**Example**:
\`\`\`typescript
// How it's implemented
code example
\`\`\`

**Extensibility**: How to extend this in the future...

添加项目约定

### Convention: [Convention Name]

**What**: Brief description of the convention.

**Why**: Why we do it this way in this project.

**Example**:
\`\`\`typescript
// How to follow this convention
code example
\`\`\`

**Related**: Links to related conventions or specs.

添加新模式

### Pattern Name

**Problem**: What problem does this solve?

**Solution**: Brief description of the approach.

**Example**:
\`\`\`
// Good
code example

// Bad
code example
\`\`\`

**Why**: Explanation of why this works better.

添加禁止模式

### Don't: Pattern Name

**Problem**:
\`\`\`
// Don't do this
bad code example
\`\`\`

**Why it's bad**: Explanation of the issue.

**Instead**:
\`\`\`
// Do this instead
good code example
\`\`\`

添加常见错误

### Common Mistake: Description

**Symptom**: What goes wrong

**Cause**: Why this happens

**Fix**: How to correct it

**Prevention**: How to avoid it in the future

添加易忽略的问题

> **Warning**: Brief description of the non-obvious behavior.
>
> Details about when this happens and how to handle it.

---

交互模式

如果不确定要更新什么，请回答以下问题：

1. 你刚完成了什么？

   • 修复了一个错误
   • 实现了一项功能
   • 重构了代码
   • 讨论了某种方案

2. 你学到了什么或做出了什么决定？

   • 设计决策（为什么选 X 而非 Y）
   • 项目约定（如何执行某项操作）
   • 不明显的行为（易忽略的问题）
   • 更好的方案（模式）

3. 未来的 AI/开发者需要了解这些吗？

   • 为了理解代码的工作原理 → 是，更新规范
   • 为了维护或扩展功能 → 是，更新规范
   • 为了避免重复犯错 → 是，更新规范
   • 纯粹一次性的实现细节 → 可以考虑跳过

4. 这与哪个领域有关？

   • 后端代码
   • 前端代码
   • 跨层数据流
   • 代码组织/复用
   • 质量/测试

---

质量检查清单

完成代码规范更新前：

• 内容是否具体且可执行？
• 是否包含代码示例？
• 是否解释了原因（WHY），而不只是内容（WHAT）？
• 是否包含可执行的签名/约定？
• 是否包含验证和错误矩阵？
• 是否包含良好/一般/糟糕的案例？
• 是否包含带断言点的必需测试？
• 是否放在了正确的代码规范文件中？
• 是否与现有内容重复？
• 新团队成员能否看懂？

---

与其他命令的关系

Development Flow:
  Learn something → `update-spec` (Trellis command) → Knowledge captured
       ↑                                  ↓
  `break-loop` (Trellis command) ←──────────────────── Future sessions benefit
  (deep bug analysis)

• ``break-loop（Trellis 命令） - 深入分析错误，通常会发现需要更新规范的地方
• ``update-spec（Trellis 命令） - 实际执行更新
• ``finish-work（Trellis 命令） - 提醒你检查是否需要更新规范

---

核心理念

代码规范是不断演进的文档。每次调试会话、每个“顿悟时刻”，都是让实现约定更清晰的机会。

目标是建立组织记忆：

• 一个人学到的东西，所有人都能受益
• AI 在一次会话中学到的内容，会延续到未来的会话中
• 错误会转化为有据可循的防护措施