更新代码规范 - 沉淀可执行契约

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

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

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

在本项目中，实现工作的"规范"指的是代码规范：

•可执行的契约（不是仅有原则的文字）
•具体的签名、载荷字段、环境变量键和边界行为
•可测试的验证/错误行为

如果变更涉及基础设施或跨层契约，代码规范深度是强制的。

必需的章节（基础设施/跨层规范）：

•范围 / 触发条件
•签名（命令/API/DB）
•契约（请求/响应/环境变量）
•验证与错误矩阵
•Good/Base/Bad 用例
•必需的测试（含断言点）
•错误 vs 正确（至少一对）

何时更新代码规范

触发条件	示例	目标规范
实现了一个功能	用 giget 添加了模板下载	相关的 `backend/` 或 `frontend/` 文件
做了设计决策	使用 type 字段 + 映射表实现可扩展性	相关代码规范 + "设计决策"章节
修复了一个 Bug	发现了错误处理的微妙问题	`backend/error-handling.md`
发现了一个模式	找到了更好的代码组织方式	相关的 `backend/` 或 `frontend/` 文件
踩了一个坑	发现 X 必须在 Y 之前完成	相关代码规范 + "常见错误"章节
建立了一个约定	团队商定了命名模式	`quality-guidelines.md`
新的思维触发	"做 Y 之前别忘了检查 X"	`guides/*.md`（作为检查清单项，不是详细规则）

关键洞察：代码规范更新不仅仅是为了问题。每次功能实现都包含设计决策和契约，未来的 AI/开发者需要这些来安全地执行。

规范结构概览

code

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

关键：代码规范 vs 指南 - 区分清楚

类型	位置	用途	内容风格
代码规范	`backend/.md`, `frontend/.md`	告诉 AI "如何安全地实现"	签名、契约、矩阵、用例、测试点
指南	`guides/*.md`	帮助 AI "该思考什么"	检查清单、问题、指向规范的指针

决策规则：问自己：

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

示例：

学到的东西	错误位置	正确位置
"用 `reconfigure()` 而不是 `TextIOWrapper` 处理 Windows 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：阅读目标代码规范

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

•理解现有结构
•避免重复内容
•找到适合你更新的章节

bash

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

步骤 4：进行更新

遵循以下原则：

•要具体：包含具体示例，不只是抽象规则
•解释为什么：说明这能防止什么问题
•展示契约：添加签名、载荷字段和错误行为
•展示代码：为关键模式添加代码片段
•保持简短：每个章节一个概念

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

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

更新模板

基础设施/跨层工作的强制模板

markdown

## 场景：<名称>

### 1. 范围 / 触发条件
- 触发条件：<为什么需要代码规范深度>

### 2. 签名
### 3. 契约
### 4. 验证与错误矩阵
### 5. Good/Base/Bad 用例
### 6. 必需的测试
### 7. 错误 vs 正确
#### 错误
...
#### 正确
...

添加设计决策

markdown

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

**背景**：我们在解决什么问题？

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

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

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

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

添加项目约定

markdown

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

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

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

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

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

添加新模式

markdown

### 模式名称

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

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

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

// 不好的
代码示例
\`\`\`

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

添加禁止模式

markdown

### 不要：模式名称

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

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

**应该这样**：
\`\`\`
// 这样做
正确代码示例
\`\`\`

添加常见错误

markdown

### 常见错误：描述

**症状**：出了什么问题

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

**修复**：如何纠正

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

添加陷阱

markdown

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

交互模式

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

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

质量检查清单

完成代码规范更新前：

与其他命令的关系

code

开发流程：
  学到东西 → $update-spec → 知识已沉淀
       ↑                                  ↓
  $break-loop ←──────────────────── 未来的会话受益
  （深度 Bug 分析）

•$break-loop - 深度分析 Bug，通常揭示需要更新的规范
•$update-spec - 实际进行更新（本 Skill）
•$finish-work - 提醒你检查规范是否需要更新

核心理念

代码规范是活文档。每次调试会话、每个"啊哈"时刻都是让实现契约更清晰的机会。

目标是组织记忆：

•一个人学到的，所有人受益
•AI 在一次会话中学到的，持续到未来的会话
•错误变成文档化的护栏