zengchuan/saas-mbr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
54c21876e4ec8d7a751d5c0b84938c8160a9d7a3
saas-mbr/abacus.springboot.example/.project.agents/SELF_CONSTRAINTS.md
T

7.1 KiB
Raw Blame History

Agent 自我约束清单（本项目硬规则）

这是 Agent 在本项目工作时必须遵守的硬约束。每次开工前自查本清单，违反任何一条都应先停下，与用户对齐后再继续。 完整背景与原理请见 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 不明显时写一行。
  • 不写解释 WHAT 的注释（命名应自解释）。
  • 不写"为某 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 写日志）
  • 会话即将结束前（确认兜底日志已写）
Reference in New Issue View Git Blame Copy Permalink