🔧 chore(templates): align agent templates and docs

- drop implementation-plan template and references - add AGENT_RULES.local.md precedence in templates - add plan meta guidance and CN updates
2026-01-23 11:37:29 +08:00
parent efb93f14c1
commit eb75036b64
8 changed files with 138 additions and 199 deletions
@@ -1,12 +1,13 @@
-# Agent Instructions
+# 代理指引

 <!-- playbook:framework:start -->

 ## 规则优先级

 1. 系统/开发者指令与安全约束
-2. 仓库规则：`.agents/` 与本文件
-3. `AGENT_RULES.md` - 执行流程
+2. 项目私有规则：`AGENT_RULES.local.md`（如存在）
+3. 仓库规则：`.agents/` 与本文件
+4. `AGENT_RULES.md` - 执行流程

 ---

@@ -24,6 +25,7 @@

 ### 核心规则

+- **项目私有规则**：[AGENT_RULES.local.md](./AGENT_RULES.local.md)
 - **执行流程**：[AGENT_RULES.md](./AGENT_RULES.md)
 - **AI 行为规范**：[docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md)

@@ -34,7 +36,6 @@
 - **架构设计**：[memory-bank/architecture.md](memory-bank/architecture.md)
 - **进度追踪**：[memory-bank/progress.md](memory-bank/progress.md)
 - **架构决策**：[memory-bank/decisions.md](memory-bank/decisions.md)
- **实施计划**：[memory-bank/implementation-plan.md](memory-bank/implementation-plan.md)

 ### 工作流程

@@ -48,10 +49,11 @@

 **AI 应该做的**：

-1. 读取 [AGENT_RULES.md](./AGENT_RULES.md)
-2. 读取 [memory-bank/](memory-bank/) 核心文档
-3. 读取 [docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md)
-4. 查看 `docs/plans/` 下最新计划（如有）或 `memory-bank/implementation-plan.md`
+1. 读取 [AGENT_RULES.local.md](./AGENT_RULES.local.md)（如存在）
+2. 读取 [AGENT_RULES.md](./AGENT_RULES.md)
+3. 读取 [memory-bank/](memory-bank/) 核心文档
+4. 读取 [docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md)
+5. 查看 `docs/plans/` 下最新计划（如有）
 <!-- playbook:framework:end -->

 ---
@@ -5,18 +5,19 @@
 ## 优先级

 1. 系统/开发者指令与安全约束
-2. 仓库规则：`.agents/` 与 `AGENTS.md`
-3. 本文件
+2. 项目私有规则：`AGENT_RULES.local.md`（如存在）
+3. 仓库规则：`.agents/` 与 `AGENTS.md`
+4. 本文件

 ## 上下文加载（每次会话开始）

 **必读文档**（按顺序）：

-1. `memory-bank/project-brief.md` - 项目定位、边界、约束
-2. `memory-bank/tech-stack.md` - 技术栈、工具链
-3. `memory-bank/architecture.md` - 架构设计、模块职责
-4. `docs/plans/` - 最新实施计划（如存在）
-5. `memory-bank/implementation-plan.md` - 当前实施计划（如存在）
+1. `AGENT_RULES.local.md` - 项目私有规则（如存在，优先级高于本文件）
+2. `memory-bank/project-brief.md` - 项目定位、边界、约束
+3. `memory-bank/tech-stack.md` - 技术栈、工具链
+4. `memory-bank/architecture.md` - 架构设计、模块职责
+5. `docs/plans/` - 最新实施计划（如存在）

 **目的**：让 AI 快速理解项目全貌，避免重复解释。

@@ -33,6 +34,13 @@

 ## Plan 规则

+- **Plan Meta 必填**：Plan 头部 `---` 之后、Task 1 之前插入 `## Plan Meta`，包含：
+  - `Plan Group`（归类任务）
+  - `Parent Plan`（上层/集成计划链接）
+  - `Verification Scope`（local 或 integration）
+  - `Verification Gate`（must-pass）
+- **不允许中断任务**：Plan 中不应包含必然失败或依赖未确认的信息；未确认项必须在 brainstorming 阶段解决后再产出 Plan
+- **验证必须可通过**：Plan 内验证应为当前阶段可通过的局部验证；需要集成验证的内容放入上层/集成 Plan
 - 不因等待确认而中断可执行步骤；待确认事项在回复中列出
 - 执行并验证该 Plan 中所有可执行的子任务
 - 若因缺少信息/决策而阻塞：在 `memory-bank/progress.md` 记录阻塞原因
@@ -14,8 +14,7 @@ templates/
 │   ├── tech-stack.template.md
 │   ├── architecture.template.md
 │   ├── progress.template.md
-│   ├── decisions.template.md
-│   └── implementation-plan.template.md
+│   └── decisions.template.md
 ├── prompts/                     # 提示词库模板
 │   ├── README.md
 │   ├── system/
@@ -82,13 +81,13 @@ scripts\sync_templates.bat -project-root C:\path\to\project -full
 project/
 ├── AGENTS.md              # 路由中心（主入口）
 ├── AGENT_RULES.md         # 执行流程
+├── AGENT_RULES.local.md   # 项目私有规则（可选，手动维护）
 ├── memory-bank/           # 项目上下文
 │   ├── project-brief.md
 │   ├── tech-stack.md
 │   ├── architecture.md
 │   ├── progress.md
-│   ├── decisions.md
-│   └── implementation-plan.md
+│   └── decisions.md
 └── docs/prompts/          # 提示词库
    ├── README.md
    ├── system/agent-behavior.md
@@ -123,7 +122,6 @@ project/
 | `architecture.template.md`        | 架构设计、模块职责   |
 | `progress.template.md`            | 开发进度追踪         |
 | `decisions.template.md`           | 架构决策记录（ADR）  |
-| `implementation-plan.template.md` | 当前实施计划         |

 ### prompts/

@@ -138,6 +136,31 @@ project/
 ### AGENT_RULES.template.md

 执行流程规范，定义 AI 的工作循环和约束。
+如需项目私有规则，建议创建 `AGENT_RULES.local.md`，其优先级高于 `AGENT_RULES.md`，
+且不会被同步脚本覆盖。
+
+### 示例：不跑测试的计划提示词
+
+当你需要修改代码但暂时不运行测试时，可用以下提示词生成“可执行且不失败”的实施计划：
+
+```text
+你是 Codex。先使用 $brainstorming。
+目标：修改 <模块/功能>，细节如下：<你的需求>
+约束：
+- 不跑任何测试（test/ci），但允许做可通过的局部验证（格式化/静态检查/人工 diff）。
+- Plan 不能包含任何必然失败或未确认的任务；所有依赖必须在 brainstorming 阶段确认清楚。
+- 采用 writing-plans 的固定头部格式，且在 `---` 之后追加 `## Plan Meta`：
+  - Plan Group: <X>
+  - Parent Plan: <docs/plans/...-design.md>
+  - Verification Scope: local
+  - Verification Gate: must-pass
+
+流程：
+1) 先完成 brainstorming，并输出设计文档 `docs/plans/YYYY-MM-DD-<topic>-design.md`。
+2) 询问我“是否进入 `docs/plans/` 实施计划编写阶段”，确认后使用 writing-plans 生成实现计划。
+3) 实现计划内明确标注每步要改的文件与命令；验证步骤只包含可通过的局部验证，不包含测试。
+4) 执行计划并更新 `memory-bank/progress.md`。
+```

 ### AGENTS.template.md

@@ -1,91 +0,0 @@
-# 当前实施计划
-
-## 计划状态
-
-**计划名称**: {{PLAN_NAME}}
-**开始时间**: {{START_DATE}}
-**当前状态**: 进行中 / 已完成 / 已暂停
-
---
-
-## 目标
-
-{{PLAN_GOAL}}
-
-**成功标准**:
-
- [ ] {{SUCCESS_CRITERIA_1}}
- [ ] {{SUCCESS_CRITERIA_2}}
- [ ] {{SUCCESS_CRITERIA_3}}
-
---
-
-## 实施步骤
-
-### 阶段 1: {{PHASE_1_NAME}}
-
-#### 步骤 1.1: {{STEP_1_1}}
-
- [ ] {{TASK_1_1_1}}
- [ ] {{TASK_1_1_2}}
-
-**验证**: {{VERIFICATION_1_1}}
-
-#### 步骤 1.2: {{STEP_1_2}}
-
- [ ] {{TASK_1_2_1}}
- [ ] {{TASK_1_2_2}}
-
-**验证**: {{VERIFICATION_1_2}}
-
---
-
-### 阶段 2: {{PHASE_2_NAME}}
-
-#### 步骤 2.1: {{STEP_2_1}}
-
- [ ] {{TASK_2_1_1}}
- [ ] {{TASK_2_1_2}}
-
-**验证**: {{VERIFICATION_2_1}}
-
---
-
-## 当前进度
-
-### 已完成
-
- {{COMPLETED_PHASE}}
-
-### 进行中
-
- {{IN_PROGRESS_STEP}}
-
-### 待开始
-
- {{PENDING_STEP}}
-
---
-
-## 风险与问题
-
-### 风险
-
-1. **{{RISK_1}}**
-   - 风险：{{RISK_1_DESC}}
-   - 缓解：{{RISK_1_MITIGATION}}
-
-### 已解决的问题
-
-1. {{RESOLVED_ISSUE_1}}
-
---
-
-## 下一步行动
-
- [ ] {{NEXT_ACTION_1}}
- [ ] {{NEXT_ACTION_2}}
-
---
-
-**最后更新**：{{DATE}}