name: update-spec description: “更新规范 - 将知识捕获到规范中”

更新规范 - 将知识捕获到规范中

当您学到有价值的东西时（来自调试、实现或讨论），使用此技能更新相关的规范文档。

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

何时更新规范

触发器	示例	目标规范
实现了一个功能	添加了使用 giget 的模板下载	相关的 `backend/` 或 `frontend/` 文件
做出了设计决策	使用类型字段 + 映射表以实现可扩展性	相关规范 + “设计决策” 部分
修复了一个错误	发现错误处理的微妙问题	`backend/error-handling.md`
发现了一个模式	找到了更好的代码结构方式	相关的 `backend/` 或 `frontend/` 文件
遇到了陷阱	了解到 X 必须在 Y 之前完成	相关规范 + “常见错误” 部分
建立了一个约定	团队就命名模式达成一致	`quality-guidelines.md`
新的思考触发器	“在完成 Y 之前不要忘记检查 X”	`guides/*.md`（作为检查清单项，不是详细规则）

关键洞察：规范更新不仅针对问题。每个功能实现都包含未来 AI/开发者需要知道的设计决策和项目约定。

规范结构概述

.trellis/spec/
├── backend/           # 后端编码标准
│   ├── index.md       # 概述和链接
│   └── *.md           # 主题特定指南
├── frontend/          # 前端编码标准
│   ├── index.md       # 概述和链接
│   └── *.md           # 主题特定指南
└── guides/            # 思考检查清单（不是编码规范！）
    ├── index.md       # 指南索引
    └── *.md           # 主题特定指南

关键：规范与指南 - 知道区别

类型	位置	目的	内容风格
规范	`backend/.md`, `frontend/.md`	告诉 AI “如何编写代码”	详细规则、代码示例、禁止模式
指南	`guides/*.md`	帮助 AI “思考什么”	检查清单、问题、指向规范的指针

决策规则：问自己：

“这是 如何编写 代码” → 放在 backend/ 或 frontend/
“这是 在编写前考虑什么” → 放在 guides/

示例：

学习内容	错误位置	正确位置
“在 Windows 上使用 `reconfigure()` 而不是 `TextIOWrapper` 来处理 stdout”	❌ `guides/cross-platform-thinking-guide.md`	✅ `backend/script-conventions.md`
“记住在编写跨平台代码时检查编码”	❌ `backend/script-conventions.md`	✅ `guides/cross-platform-thinking-guide.md`

指南应该是短的检查清单，指向规范，不要复制详细规则。

更新流程

步骤 1：识别您学到了什么

回答这些问题：

您学到了什么？（具体化）
为什么重要？（它防止什么问题？）
它属于哪里？（哪个规范文件？）

步骤 2：分类更新类型

类型	描述	操作
设计决策	为什么选择方法 X 而不是 Y	添加到 “设计决策” 部分
项目约定	如何在这个项目中做 X	添加到相关部分并附示例
新模式	发现的可重用方法	添加到 “模式” 部分
禁止模式	导致问题的东西	添加到 “反模式” 或 “不要” 部分
常见错误	容易犯的错误	添加到 “常见错误” 部分
约定	达成一致的标准	添加到相关部分
陷阱	非显而易见的行为	添加警告提示

步骤 3：阅读目标规范

在编辑前，阅读当前规范以：

理解现有结构
避免重复内容
为更新找到正确部分

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

步骤 4：进行更新

遵循这些原则：

具体化：包括具体示例，不仅仅是抽象规则
解释原因：说明防止的问题
展示代码：为模式添加代码片段
保持简短：每个部分一个概念

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

如果添加了新部分或规范状态更改，更新类别的 index.md。

更新模板

添加设计决策

### 设计决策：[决策名称]

**上下文**：我们正在解决什么问题？

**考虑过的选项**：
1. 选项 A - 简要描述
2. 选项 B - 简要描述

**决策**：我们选择选项 X，因为...

**示例**：
\`\`\`typescript
// 如何实现
代码示例
\`\`\`

**可扩展性**：如何未来扩展这个...

添加项目约定

### 约定：[约定名称]

**什么**：约定的简要描述。

**为什么**：为什么在这个项目中这样做。

**示例**：
\`\`\`typescript
// 如何遵循此约定
代码示例
\`\`\`

**相关**：指向相关约定或规范的链接。

添加新模式

### 模式名称

**问题**：解决什么问题？

**解决方案**：方法的简要描述。

**示例**：
\`\`\`
// 好的
代码示例

// 坏的
代码示例
\`\`\`

**为什么**：解释为什么这个更好。

添加禁止模式

### 不要：模式名称

**问题**：
\`\`\`
// 不要这样做
坏代码示例
\`\`\`

**为什么不好**：问题的解释。

**替代方案**：
\`\`\`
// 这样做替代
好代码示例
\`\`\`

添加常见错误

### 常见错误：描述

**症状**：什么出错

**原因**：为什么发生

**修复**：如何纠正

**预防**：如何未来避免

添加陷阱

> **警告**：非显而易见行为的简要描述。
>
> 关于何时发生以及如何处理它的详细信息。

交互模式

如果您不确定要更新什么，回答这些提示：

您刚刚完成了什么？
- [ ] 修复了一个错误
- [ ] 实现了一个功能
- [ ] 重构了代码
- [ ] 讨论了方法
您学到或决定了什么？
- 设计决策（为什么 X 而不是 Y）
- 项目约定（如何做 X）
- 非显而易见行为（陷阱）
- 更好的方法（模式）
未来 AI/开发者需要知道这个吗？
- 理解代码如何工作 → 是，更新规范
- 维护或扩展功能 → 是，更新规范
- 避免重复错误 → 是，更新规范
- 纯粹一次性实现细节 → 可能跳过
它涉及哪个领域？
- [ ] 后端代码
- [ ] 前端代码
- [ ] 跨层数据流
- [ ] 代码组织/重用
- [ ] 质量/测试

质量检查清单

完成规范更新前：

[ ] 内容具体且可操作吗？
[ ] 您包括代码示例了吗？
[ ] 您解释原因而不仅仅是内容了吗？
[ ] 它在正确的规范文件中吗？
[ ] 它重复了现有内容吗？
[ ] 新团队成员能理解吗？

与其他命令的关系

开发流程：
  学到东西 → $update-spec → 知识被捕获
       ↑                                  ↓
  $break-loop ←──────────────────── 未来会话受益
  （深度错误分析）

$break-loop - 深度分析错误，经常揭示需要规范更新
$update-spec - 实际进行更新（此技能）
$finish-work - 提醒您检查是否需要更新规范

核心哲学

规范是活文档。每个调试会话、每个“顿悟时刻”都是使规范更好的机会。

目标是 制度记忆：

一个人学到的东西，每个人都受益
AI 在一个会话中学到的东西，持久到未来会话
错误成为文档化的护栏