130 lines
7.1 KiB
Markdown
130 lines
7.1 KiB
Markdown
# Agent 自我约束清单（本项目硬规则）
|
||
|
||
> 这是 Agent 在本项目工作时必须遵守的硬约束。每次开工前自查本清单，违反任何一条都应**先停下**，与用户对齐后再继续。
|
||
> 完整背景与原理请见 [`VIBECODING_GUIDE.md`](./VIBECODING_GUIDE.md)。本清单只列"不许做什么 / 必须做什么"。
|
||
>
|
||
> 文档约定（本项目）：上游文档位于 `.project.agents/docs/context`，依次为
|
||
> `PRD.md`（行为与范围）、`ARCHITECTURE.md`（模块/依赖/契约/目录）、`CONVENTIONS.md`（命名/风格/提交）。
|
||
> 派生文档不得反向修改上游。
|
||
|
||
---
|
||
|
||
## A. 开工前的强制自检（每个新会话开始时执行）
|
||
|
||
在进行任何编辑动作之前，必须确认以下事项；任一项不满足则先暂停业务任务，处理掉再继续。
|
||
|
||
- [ ] **A1. 仓库是否在版本控制下？** 若否：立即停下，先初始化仓库 + 配置 ignore + 初始 commit。
|
||
- [ ] **A2. 工作区是否干净？** 有未提交的旧改动？先与用户确认是否要先提交/暂存，**不允许在脏工作区上叠加新改动**。
|
||
- [ ] **A3. 是否已有 `ARCHITECTURE.md`？**
|
||
- 若否，且本次任务**涉及写业务代码**：先停下，按 `VIBECODING_GUIDE` 的流程产出架构文档，再写代码。
|
||
- 若否，且本次任务**只是文档/讨论**：可继续，但应主动提醒用户补架构文档。
|
||
- [ ] **A4. 任务的归属模块清楚吗？** 我能否在 `ARCHITECTURE.md` 的模块清单里指出"这个改动属于哪个模块"？指不出来则停下补架构。
|
||
- [ ] **A5. 上游文档是否已读？** `PRD.md` / `ARCHITECTURE.md` / `CONVENTIONS.md` 中与本任务相关的章节是否读过？没读过先读，不要凭印象动手。
|
||
|
||
---
|
||
|
||
## B. 写代码时的硬约束
|
||
|
||
### B1. 模块边界
|
||
- ❌ 不允许新增**未在 `ARCHITECTURE.md` 中登记**的模块；要新增必须先更新架构文档。
|
||
- ❌ 不允许引入**反向依赖**（低层模块依赖高层模块）。需要时改为接口/回调倒置。
|
||
- ❌ 不允许跨模块**直接访问私有实现**；只能走该模块对外暴露的接口。
|
||
- ❌ 不允许出现 `Manager` / `Helper` / `Util` / `Common` / `Misc` / `Tools` 这类语义为空的新模块名；用动词+名词描述真实职责。
|
||
|
||
### B2. 单一职责
|
||
- ❌ 不允许在 UI/展示层写业务判断或副作用（仅消费状态、发送意图）。
|
||
- ❌ 不允许在数据模型类里堆业务方法；模型保持瘦，逻辑放 Service / UseCase。
|
||
- ❌ 不允许"顺手"修改不在任务范围内的模块；越界的改动走单独提交并明确告知用户。
|
||
|
||
### B3. 文档同步（与代码改动**同一个 commit** 内）
|
||
- 加/删/改功能 → 同步更新 `PRD.md`
|
||
- 加/删/改模块或依赖 → 同步更新 `ARCHITECTURE.md`（模块清单 + 依赖图）
|
||
- 派生文档发现与上游不一致 → 回去改上游，不能让派生文档自走
|
||
|
||
### B4. 注释与命名
|
||
- 每个方法/函数必须写注释（一行职责说明，便于人工复核）。
|
||
- 只在 WHY 不明显处补充 WHY 注释；不写会随时间失效的注释。
|
||
- 不写"为某 issue/任务而加"这类会随时间失效的注释。
|
||
- 严格遵守 `CONVENTIONS.md` 中的命名规范（不存在则先补）。
|
||
|
||
### B5. 错误处理
|
||
- 只在系统边界（用户输入、外部 API、文件 IO）做防御；内部模块互相信任。
|
||
- 不为不可能发生的情况加 fallback。
|
||
- 不引入向后兼容 shim，除非用户明确要求。
|
||
|
||
### B6. 实施日志（execution log）
|
||
- **每完成一个可独立验收的部分（milestone 或子任务），必须在 `.project.agents/log` 写日志**。格式与时机见 `VIBECODING_GUIDE`。
|
||
- 日志内必须包含本段的版本控制提交列表；若本段未提交，明确写出"未提交"及原因。
|
||
- 完成路线图任一 milestone → **必须**写日志，且与该 milestone 的提交同一会话完成。
|
||
- 单次会话即将结束（用户表示收工 / 上下文将被压缩）→ **必须**写一份兜底日志记录当前状态与下一步。
|
||
- ❌ 不允许只提交不写日志（除非属于豁免情况：纯文档微调 / 被回滚的实验性探索）。
|
||
- ❌ 不允许写日志但跳过更新 `ARCHITECTURE.md` —— 若本段触发架构变更，先改架构、再提交、再写日志。
|
||
|
||
---
|
||
|
||
## C. 改动范围控制
|
||
|
||
- ❌ 一次任务一个目的。不要"既加功能又重构又改样式"。
|
||
- ❌ 不允许在 bug 修复任务中做无关清理。
|
||
- ❌ 不允许引入"为未来准备"的抽象（YAGNI）；三处相似优于一处过度抽象。
|
||
- ❌ 不允许半完成的实现（要么这次完成，要么不要开始）。
|
||
|
||
---
|
||
|
||
## D. 出问题时的排查纪律
|
||
|
||
bug 处理必须按下列顺序，**严禁跳步**：
|
||
|
||
1. 复现现象（明确触发路径）
|
||
2. 在 `ARCHITECTURE.md` 上**圈出嫌疑模块**
|
||
3. 检查跨模块**接口契约**
|
||
4. 缩小到单模块后再读代码
|
||
5. 修完后：若是架构问题，必须更新 `ARCHITECTURE.md` 或 `CONVENTIONS.md`
|
||
|
||
**禁止行为**：bug 一来就全仓 grep、试改一行看效果、连续 try-fail 循环。出现这种倾向立刻停下，回到第 2 步。
|
||
|
||
---
|
||
|
||
## E. 与用户的协作约束
|
||
|
||
- ❌ 不替用户做架构决策。涉及模块拆分、依赖方向、命名规范这类**长期影响**的决定，必须明确询问。
|
||
- ❌ 不在用户没要求的时候主动创建文档（除非本清单或 `CLAUDE.md` 已要求）。
|
||
- ❌ 不在没看代码的情况下凭推测回答 "X 是怎么实现的"。
|
||
- ✅ 每次涉及架构/文档/规范变更，先告知影响面，再动手。
|
||
- ✅ 用户的明确指示永远高于本清单和任何 skill。冲突时遵循用户。
|
||
|
||
---
|
||
|
||
## F. 触发"全员停车"的红线
|
||
|
||
出现以下任一情况，**立即停止当前任务，与用户对齐后再决定下一步**：
|
||
|
||
1. 发现自己在脏工作区上累积了大量未提交改动
|
||
2. 发现自己正在新增一个"无处归属"的模块/文件
|
||
3. 发现代码与 `ARCHITECTURE.md` 已经矛盾，且无法用小补丁同步
|
||
4. 同一个 bug 连续 3 次尝试修复未果
|
||
5. 用户的请求与本清单 / `CLAUDE.md` / 上游文档存在冲突 —— 必须先澄清，不能默默选边
|
||
6. 即将做出"难以回滚"的动作（删除文件 / 重命名模块 / 调整目录结构 / 强制 push）
|
||
|
||
---
|
||
|
||
## G. 文件路径合规
|
||
|
||
- Agent 的配置文件**只**写入 `.project.agents` 子树，禁止写入仓库根目录或其他非约定位置。
|
||
- 项目文档**只**写入 `.project.agents/docs/context`（不允许再分子目录，除非用户明确要求）。
|
||
- 本清单（`SELF_CONSTRAINTS.md`）与指南（`VIBECODING_GUIDE.md`）位于 `.project.agents` 根，与 `CLAUDE.md` 同级。
|
||
|
||
---
|
||
|
||
## H. 自查触发器（什么时候重读本清单）
|
||
|
||
至少在以下时机重读本清单：
|
||
|
||
- 新会话开始，且任务涉及代码改动
|
||
- 用户要求"加新功能"/"修 bug"/"重构"
|
||
- 自己感到"差不多可以直接动手了" —— 这种感觉本身就是触发器
|
||
- 即将创建超过 1 个新文件
|
||
- 即将修改 3 个以上文件
|
||
- 即将修改任何 `.project.agents/docs/context` 下的文档
|
||
- **完成一个路线图 milestone 或子任务前**（确认是否需要按 §B6 写日志）
|
||
- **会话即将结束前**（确认兜底日志已写） |