saas-mbr/abacus.springboot.example/.project.agents/SELF_CONSTRAINTS.md

# 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，除非用户明确要求。

### B7. 多租户隔离（SaaS 硬约束）
- 任何数据访问（JPA / 原生 SQL / 编排）必须带 `tenant_id` 过滤；缓存 key 必须前缀 `tenant:{tenantId}:`。
- 租户标识以 token 为准，禁止在业务参数 / URL 中传递 tenantId；跨租户操作须 `@CrossTenant` + 审批。
- 前端：品牌/主题/菜单须按 `tenantConfig` 动态加载，禁止硬编码；`X-Tenant-Id` 头由 `request.ts` 自动附加，业务代码不得手写。
- 详细设计与落地映射见 `docs/architecture.md §7`、`coding-standards.md §9`；本仓库 `ARCHITECTURE.md §10`。

### 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 写日志）
- **会话即将结束前**（确认兜底日志已写）