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

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

当你学到有价值的东西时（从调试、实施或讨论中），使用此命令更新相关的规范文档。

时机：完成任务、修复bug或发现新pattern后

何时更新规范

触发点	例子	目标规范
实现功能	添加了模板下载功能，使用giget	相关`backend/`或`frontend/`文件
做出设计决策	使用类型字段+映射表实现可扩展性	相关规范+“设计决策”部分
修复bug	发现错误处理的细微问题	`backend/error-handling.md`
发现pattern	找到更好的代码结构方式	相关`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 stdout中使用`reconfigure()`而非`TextIOWrapper`”	❌ `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	添加到相关部分，带示例
新pattern	发现的可重用方法	添加到“Patterns”部分
禁止模式	导致问题的内容	添加到“反模式”或“禁止”部分
常见错误	易犯错误	添加到“常见错误”部分
约定	达成共识的标准	添加到相关部分
坑点	不明显行为	添加警告提示

步骤3：阅读目标规范

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

理解现有结构
避免重复内容
找到更新位置

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

步骤4：进行更新

遵循这些原则：

具体：包含具体例子，非抽象规则
解释原因：说明预防的问题
展示代码：添加代码片段
简短：每部分一个概念

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

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

更新模板

添加设计决策

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

**上下文**：我们解决的问题

**考虑选项**：
1. 选项A - 简短描述
2. 选项B - 简短描述

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

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

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

添加项目约定

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

**内容**：约定简要描述。

**原因**：为什么本项目这样做。

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

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

添加新pattern

### Pattern名称

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

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

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

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

**原因**：解释为什么更好。

添加禁止模式

### 禁止：Pattern名称

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

**为何不好**：问题解释。

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

添加常见错误

### 常见错误：描述

**症状**：出错内容

**原因**：为何发生

**修复**：如何纠正

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

添加坑点

> **警告**：不明显行为的简短描述。
>
> 发生时详情及处理方式。

交互模式

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

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

质量检查表

完成规范更新前：

[ ] 内容具体且可操作吗？
[ ] 包含代码示例吗？
[ ] 解释原因而非仅是什么吗？
[ ] 在正确规范文件吗？
[ ] 重复现有内容吗？
[ ] 新团队成员能理解吗？

与其他命令的关系

开发流程：
  学到东西 → /trellis:update-spec → 知识捕获
       ↑                                  ↓
  /trellis:break-loop ←──────────────────── 未来会话受益
  （深入bug分析）

/trellis:break-loop - 深度分析bug，常揭示规范更新需求
/trellis:update-spec - 实际进行更新（此命令）
/trellis:finish-work - 提醒检查规范是否需要更新

核心理念

规范是活文档。每次调试会话、每个“顿悟时刻”都是改进规范的机会。

目标是机构记忆：

一人所学，人人受益
AI一次会话所学，延续到未来会话
错误成为文档化护栏