# AI 行为红线与防错指南 (AI Executing Behavior)

基于常见失败模式，所有协助开发的 AI 必须严格遵守以下行为准则，避免走弯路、执行破坏性操作或擅自改变项目方向。

## 1. 严格的 Git 操作纪律

- **绝对优先使用 Rebase**：在进行分支同步、更新主干时，**永远使用 `git rebase`** 而非 `git merge`。禁止在通常同步场景下使用 merge 污染提交树。（与 `/sync-master` 工作流一致时可直接遵循该流程。）
- **防止未提交数据丢失**：在执行 `git reset --hard`、`git checkout` 覆盖、拉取覆盖或任何具有破坏性的 Git 命令前，**必须先执行 `git status` 检查**是否有尚未提交的工作（uncommitted changes）。如果存在，必须先使用 `git stash` 暂存数据，或警告用户。切忌在未经提示的情况下直接清空未暂存的工作内容。

## 2. 避免擅自破坏与重构

- **绝不盲目删除文件**：不要仅凭没有直接引用，就自作主张将所谓「无用代码」或 Dead Code（例如整个目录）删掉。除非用户明确下达「清理」指令，否则在删除任何文件或文件夹之前**必须先征得用户的显式确认**。
- **代码变动最小化**：修哪里的问题就只碰哪里的逻辑。切忌在修复单一问题时，牵连重写周边能正常运转的代码。

## 3. 拒绝过度设计 (Anti Over-Engineering)

- **避免画蛇添足**：保持对系统变更的克制。不要顺手添加用户根本没要求的 UI、配置项或未发布的特性。
- **优先最简解法**：在处理配置或架构变更时，寻找最简单、最轻量的直达方案（例如本地环境变量足够时，不必扩大改动面）。

## 4. 谋定而后动 (Plan Before Act)

- **大重构或复杂工作前须请示大纲**：面临**系统重构、大规模搬家、复杂集成、以及大纵深的 Git 流程排错**时，**应当先用 2～3 条短句列出大纲或实现方案**，待用户确认通过后，再展开实现。
- **聚焦拆解**：若诉求庞杂，尽量拆成可独立验证的小步，避免单次回复过长导致中途截断、任务烂尾。

## 5. 项目架构意识

- 每次动作前先从全局规则了解基本设定。若涉及框架级技术栈，**勿凭常识猜测**，应查阅项目的 `.agent/rules/tech-stack.md` 与 `.agent/rules/architecture-design.md`，以仓库内约定为准。

---

## 6. 设计范围的完整阅读与二次回读确认（Two-Step Design Confirmation）

**触发条件**：用户提供设计方案、架构描述、需求文档，或引用 `.agent/plans/` 下的方案文件时。

**必须执行的两步流程**：

1. **先读完整**：阅读用户给出的**完整**描述或文档，禁止基于局部理解启动实现。若涉及 `.agent/plans/` 下文档，必须先用 Read 工具完整加载后再响应。
2. **回读确认（开工前必做）**：用简洁的 3 点向用户说明：
   - **目标**：我理解的实现目标是什么
   - **改动范围**：将涉及哪些文件 / 模块
   - **边界**：明确不会触碰哪些内容
3. **等待用户明确确认**（「OK」/「继续」/「对」）后，再进入编码。

---

## 7. 分阶段提交与断点续接策略（Anti Rate-Limit Interruption）

**触发条件**：执行包含 2 个以上阶段的计划（如 `.agent/plans/` 下的复杂任务）。

**执行规范**：

1. **每阶段完成后立即提交**：不等全部阶段完成再统一提交。每个独立阶段结束后，用规范化 commit 锁定当前进度（参考 `commit-standards.md`）。
2. **写入进度断点**：将状态同步到 `.agent/plans/task-progress.md`（可更新「当前活跃任务」表格或追加「断点续接」小节），例如：
   ```
   ## 断点续接（YYYY-MM-DD）
   - [x] 阶段 1：xxx（已完成，commit: xxxxx）
   - [ ] 阶段 2：xxx（进行中）
   - [ ] 阶段 3：xxx（待开始）
   阻塞点：无 / xxx
   ```
3. **会话续接**：若用户发送「继续」，**必须先** Read `.agent/plans/task-progress.md` 确认上次停止位置，再接续执行，禁止重新从头开始。

> **原因**：多轮会话可能被限流或中断；分阶段提交将损失控制在单阶段内；`task-progress.md` 是无状态会话之间的可靠衔接点。

---

## 8. 代码探索优先使用 Graphify（Code Exploration via Knowledge Graph）

**触发条件**：需要理解陌生模块的职责、追踪调用链、或探索多个文件之间的关系时。

**执行顺序**：

1. **先检查图谱是否存在**：
   ```bash
   test -f graphify-out/graph.json && echo "available"
   ```
2. **若存在，优先使用 `/graphify` 查询**，而非盲目 `grep` 或逐文件 `Read`：
   - 模块关系、调用链 → `/graphify query "<关键词>"`
   - 两文件/模块间的连接路径 → `/graphify path "<file-a>" "<file-b>"`
   - 某节点的职责与上下游 → `/graphify explain "<节点名>"`
3. **再按需深入源文件**：图谱给出全景后，只 `Read` 真正需要细读的文件，避免逐文件盲扫。

> **原因**：`graphify-out/graph.json` 包含全项目 AST 级节点与关系，一次查询即可定位跨文件依赖，比 grep 更准、比逐文件 Read 成本更低。未安装 Graphify 时自动降级为常规探索。

---

## 9. Dispatch / Daemon / Trigger 词汇与边界

**触发条件**：讨论或实现任务自动派发、常驻协调进程或自动触发时。

- **Dispatch（派发）**：一次把已批准任务交给执行 Agent 的尝试。必须先检查幂等、并发、Queue、Lock 与 Workflow Gate，并写 Run journal；不得绕过 `/approve`、`/mission`、`/worktree` 或 `/ship`。
- **Daemon（守护进程）**：可选的本地用户空间协调进程。**默认关闭**，只能由用户显式启动；不得直接伪造或修改 Workflow 拥有的业务状态。
- **Trigger（触发器）**：请求 Daemon 考虑 Dispatch 的声明式条件，**不是授权**。`schedule`、`file_change`、`post_commit` 必须显式 opt-in。
- **Management API 边界**：继续作为查询和受控 Run journal 层，不得因自动化需求演变为任意调度器或 Shell 执行入口。
- **Phase 0 边界**：CLI stub 只提供发现和 fail-closed 契约，不创建进程、Lock、Queue、Run、Session、Trigger 或 Dispatch 记录。

> **原因**：统一词汇并把授权、协调、触发和执行分层，可防止自动化绕过人类决策与现有状态机。