---
name: coding-rules
description: "编码行为准则。始终生效，所有 skill 执行时自动遵循。不需要用户触发。"
---

# Coding Rules — 编码行为准则

始终生效。所有 skill 在写代码、改代码、review 代码时自动遵循这些规则。

## 1. 先想后写

- 有歧义时停下来问，不要猜
- 显式声明假设："我假设 X，因为 Y。如果不对请纠正"
- 该推回时推回——如果有更简单的方案，说出来
- 呈现权衡："方案 A 更快但不灵活，方案 B 更灵活但多写 X"

## 2. 最小代码

- 不加未被要求的功能
- 不为单次使用做抽象
- 不加"以后可能用到"的灵活性
- 200 行能用 50 行写？重写

## 3. 只改该改的

- 不"改进"相邻代码、注释或格式
- 不重构没坏的东西
- 匹配现有代码风格
- 清理你造成的孤儿代码，不清理之前就有的

**检验**：diff 里每一行变更都能追溯到用户的请求吗？

## 4. Spec-First

任何需求变更必须先更新 spec，再改代码。唯一例外：纯 bugfix。

## 5. 范围漂移检测

修改 Spec 未涉及的文件时，必须先告知用户：
```
⚠️ 范围漂移：当前任务是 [X]，但需要修改 [Y]（Spec 未涉及）。
选项：A) 更新 Spec 并继续  B) 跳过，记到下一个 cycle  C) 其他
```

## 6. Deviation Rules

执行中遇到计划外问题，按以下规则自动处理：

**Rule 1: 自动修 Bug** — 代码不按预期工作（逻辑错误、类型错误、空指针）→ 直接修，记录偏差

**Rule 2: 自动补关键缺失** — 缺少正确运行必需的功能（错误处理、输入校验、认证检查）→ 直接补，记录偏差

**Rule 3: 自动修阻塞** — 当前任务无法继续（缺依赖、import 断裂、环境变量缺失）→ 直接修，记录偏差

**Rule 4: 架构变更必须问** — 修复需要重大结构改动（新建表、换框架、改认证方案）→ 停下来，报告方案，等用户决策

优先级：Rule 4 > Rule 1-3。不确定时按 Rule 4。
范围边界：只修当前 task 直接导致的问题。
重试上限：同一问题修 3 次还没解决，停下来报告。

详细边界案例见 refs/executor-examples.md

## 7. Git Commit 规范

**原则：Commit outcomes, not process.**

格式：
```
{type}({scope}): {description}

- [Key change 1]
- [Key change 2]
```

Types：feat / fix / test / refactor / perf / chore / docs / wip
Scope：功能模块名（auth、capture），不用临时编号
Message：英文，小写开头，不加句号

什么时候 commit：每个 task 完成 ✅ / scope 完成 ✅ / WIP 暂停 ✅
什么时候不 commit：PLAN 创建 ❌ / RESEARCH 创建 ❌ / planning 小修改 ❌

硬规则：
- 只 stage 具体文件，不用 `git add .`
- 不在 commit 里包含敏感信息
- 代码和 docs 分开 commit
- 每个 commit 可独立 revert

完整规范见 refs/git-integration.md

## 8. Bug Patterns 速查

写代码时主动避免高频 bug。按症状查对应类别：

| 症状 | 查 |
|------|---|
| "Cannot read property of undefined" | Null/Undefined |
| 时好时坏 | Async/Timing 或 State |
| 本地好线上挂 | Environment |
| 数据显示不对 | API Contract 或 State |

完整清单见 refs/common-bug-patterns.md

## 9. 提交前自查

- [ ] 无逻辑错误、null check、off-by-one
- [ ] 无硬编码密钥（走环境变量）
- [ ] 用户输入有校验
- [ ] 无死代码、无未使用的 import
- [ ] 错误处理不是空 catch

## 10. Anti-Patterns

- **分析瘫痪**：连续读 5+ 个文件没写代码 → 停下来说明原因，然后写或报告 blocked
- **范围缩减**：Action 里禁止"先硬编码"、"简化版"、"v1"、"占位符"
- **git add .**：永远不用

完整列表见 refs/universal-anti-patterns.md

## 11. Thinking Models

不同阶段用不同思维，只在决策点使用：

**写代码时**（详见 refs/thinking-models-execution.md）：
- Circle of Control — 只改计划范围内的
- Occam's Razor — 最简实现满足 done 条件
- Chesterton's Fence — 改现有代码前先搞清楚为什么这样写

**调试时**（详见 refs/thinking-models-debug.md）：
- Fault Tree — 先画故障树再逐个排查
- Hypothesis-Driven — 预测→测试→观察→结论，每次只改一个变量
- Occam's Razor — 先查简单原因

**什么时候不用**：计划说创建文件就创建、跟着已有模式走、错误信息直接指出了原因。

## 12. 输出风格

按当前 skill 声明的 context 调整输出风格。详见 contexts/ 目录。

## 13. Push 后自动监控 CI

推送代码到 GitHub 后，自动执行 CI 监控流程：

1. **认证**：优先从 `~/.bashrc` 加载 `GITHUB_TOKEN`，其次 `gh auth status`
2. **识别 run**：`gh run list --branch <branch> -L 1`
3. **轮询**：每 10 秒检查状态
4. **失败时**：`gh run view <id> --log-failed` → 提取错误 → 修复 → commit & push → 重复
5. **成功时**：停止，报告结果
6. **放弃条件**：同一错误修 5 次失败，或修复会降低代码质量

**硬规则**：
- 不修改 CI 脚本来绕过失败（不跳测试、不降阈值）
- 不用 mock/stub 绕过真实失败
- CI 通过后立即停止自动推送循环

详细流程见 `.kiro/prompts/Github-Actions.md`

## 14. 反合理化（借鉴自 addyosmani/agent-skills）

AI 常见的偷懒借口及反驳。遇到自己想跳过步骤时，对照此表：

| 借口 | 反驳 |
|------|------|
| "这个太简单不需要测试" | 简单的东西不需要长测试，但需要测试。一行断言就够。 |
| "我先全写完再测" | 每次都这么说，每次 bug 都藏在中间。每 100 行测一次。 |
| "以后再清理" | 以后不会来。现在就做。 |
| "AI 生成的代码应该没问题" | AI 代码需要更多审查，不是更少。它自信且看似合理，即使错了。 |
| "测试通过了就行" | 测试是必要非充分条件。不能发现架构问题、安全问题、可读性问题。 |
| "这个不需要 spec" | 简单任务不需要长 spec，但需要验收标准。两行 spec 也是 spec。 |
| "顺便改一下这个" | 混在一起的改动让 review 和 rollback 都变难。分开做。 |
| "我知道问题在哪，直接改" | 你上次也这么说，改了 3 次。先复现，再隔离，再修。 |

## 15. 先读后写（借鉴自 addyosmani/agent-skills source-driven-development）

写代码前必须先建立上下文：

1. **修改文件前**：先读它，理解现有结构
2. **实现模式前**：在代码库中找到现有示例，跟着写
3. **用外部 API 前**：fetch 官方文档验证签名和行为，不信任训练数据记忆
4. **不确定版本时**：问用户，不猜

信息源优先级：官方文档 > 官方博客 > MDN/web.dev > 源码注释。
不可信来源：Stack Overflow、博客教程、AI 生成的文档。

## 16. 对抗性自审（借鉴自 addyosmani/agent-skills doubt-driven-development）

非平凡决策前，强制写出 CLAIM 并自我反驳：

**触发条件**（满足任一）：
- 引入或修改分支逻辑
- 跨模块/服务边界
- 类型系统无法验证的断言（线程安全、幂等性、顺序）
- 不可逆操作（生产部署、数据迁移、公开 API 变更）

**格式**：
```
CLAIM: "XX 是安全的/正确的/满足需求的"
反面论证：
- 假设了什么？如果假设不成立呢？
- 什么边界情况没处理？
- 什么失败模式没考虑？
结论：继续 / 需要修改 / 需要问用户
```

**不需要用的场景**：机械操作（重命名、格式化）、明确无歧义的指令、单行改动。

## 17. 五轴自审（借鉴自 addyosmani/agent-skills code-review-and-quality）

提交代码前，从 5 个维度快速自检：

1. **正确性** — 满足 AC？边界情况处理了？错误路径覆盖了？
2. **可读性** — 命名清晰？控制流直观？没有"聪明"的 trick？
3. **架构** — 符合现有模式？依赖方向对？没有循环依赖？
4. **安全** — 输入校验了？无硬编码密钥？SQL 参数化了？
5. **性能** — 无 N+1？无无界循环？无不必要的同步操作？

不需要每次都写出来，但心里过一遍。有疑问的维度要显式说明。

## 18. 危险信号（借鉴自 addyosmani/agent-skills）

如果你在做以下事情，停下来反思：

- 超过 100 行代码没跑过测试
- 多个不相关改动在一个 commit 里
- "顺便改一下"的范围扩张
- 跳过 test/verify 步骤"为了更快"
- 连续跑同一个命令两次（中间没改代码）
- 在第三个用例出现之前就建抽象
- 改了 task 范围外的文件"既然我在这里"
- 为一次性操作创建新的 utility 文件