📝 docs(playbook): refresh guidance and examples

playbook.toml.example

@@ -31,7 +31,7 @@
 # no_backup = false             # 可选：跳过备份
 
 [sync_standards]
-# langs = ["tsl", "cpp"]        # 必填：要同步的语言
+# langs = ["tsl", "cpp", "typescript"]  # 必填：要同步的语言
 # gitattr_mode = "append"       # append(补全缺失)|overwrite(覆盖)|block(插入块)|skip(跳过)
 # no_backup = false             # 可选：跳过备份（.agents/.gitattributes）
 

templates/AGENT_RULES.template.md

@@ -151,6 +151,15 @@
 - **小步快跑**：每个 Plan 应该可快速完成
 - **可验证**：每个 Plan 必须包含验证步骤
 
+## 复利工程
+
+每次 Session 结束时：
+
+- **同一错误发生 2 次以上** → 立即更新 `AGENT_RULES.local.md` 或 `memory-bank/decisions.md`，避免下次重蹈
+- **发现项目特有规律**（如特定模块的注意事项、常见陷阱）→ 沉淀到 `AGENT_RULES.local.md`
+
+> 目标：让每次 Session 的起点比上次更高。
+
 ## 执行约束
 
 ### 代码修改
@@ -180,6 +189,16 @@
 - **避免循环**：避免重复调用同一工具获取相同信息
 - **优先专用工具**：文件操作用 Read/Edit/Write，搜索用 Grep/Glob
 
+## Context 管理
+
+以下情况应建议用户**开启新 Session**：
+
+- 当前方向明显跑偏，需要从头重新理解需求
+- 讨论阶段产生了多个候选方案，进入执行阶段时应清空对话
+- Session 过长导致注意力涣散，重复犯同类错误
+
+> 新 Session 在干净 context 下工作效果更好；切换不是失败，是重置起点。
+
 ## 需要确认的场景
 
 **常规模式**（可交互）：

templates/README.md

@@ -21,7 +21,8 @@ templates/
 │   │   └── agent-behavior.template.md
 │   ├── coding/
 │   │   ├── clarify.template.md
-│   │   └── review.template.md
+│   │   ├── review.template.md
+│   │   └── code-review.template.md
 │   └── meta/
 │       └── prompt-generator.template.md
 ├── ci/                          # CI 模板
@@ -214,6 +215,7 @@ project/
 | `system/agent-behavior.template.md` | 工作模式参考   | 切换探索/开发/调试模式 |
 | `coding/clarify.template.md`        | 需求澄清模板   | 需求不明确时           |
 | `coding/review.template.md`         | 复盘总结模板   | Plan 完成后复盘        |
+| `coding/code-review.template.md`    | 代码评审流程   | 执行 MR/PR 代码评审    |
 | `meta/prompt-generator.template.md` | 元提示词生成器 | 创建新的专用提示词     |
 
 ### AGENT_RULES.template.md

templates/prompts/README.md

@@ -11,7 +11,8 @@ prompts/
 │   └── agent-behavior.md  # 工作模式参考
 ├── coding/
 │   ├── clarify.md         # 需求澄清模板
-│   └── review.md          # 复盘总结模板
+│   ├── review.md          # 复盘总结模板
+│   └── code-review.md     # MR/PR 代码评审流程
 └── meta/
     └── prompt-generator.md # 元提示词生成器
 ```
@@ -23,6 +24,7 @@ prompts/
 | **agent-behavior.md**   | 切换工作模式（探索/开发/调试） |
 | **clarify.md**          | 需求不明确时澄清               |
 | **review.md**           | Plan 完成后复盘总结            |
+| **code-review.md**      | 执行 MR/PR 代码评审            |
 | **prompt-generator.md** | 创建新的专用提示词             |
 
 ## 工作流程
@@ -36,6 +38,8 @@ prompts/
     ↓
 执行计划 → AGENT_RULES 主循环（留痕）
     ↓
+代码评审（有 MR/PR 时）→ code-review.md
+    ↓
 完成复盘 → review.md
     ↓
 沉淀提示词 → prompt-generator.md（可选）

templates/prompts/coding/code-review.template.md

@@ -0,0 +1,81 @@
+# Code Review 流程
+
+## 触发场景
+
+收到 MR/PR 需要评审时。
+
+## 准备
+
+切换到对应分支并获取变更内容：
+
+```bash
+# GitLab
+glab mr checkout <MR_ID>
+glab mr view <MR_ID> | cat
+glab mr diff <MR_ID> | cat
+
+# GitHub
+gh pr checkout <PR_NUMBER>
+gh pr view <PR_NUMBER>
+gh pr diff <PR_NUMBER>
+```
+
+## 评审流程
+
+逐步执行以下维度。改动简单时可跳过某些步骤。
+
+### 1. 理解业务目标
+
+- 能否理解本次改动的业务目标？
+- 如果目标不明确，先确认再评审。
+
+### 2. High-level Review
+
+- 改动是否放在了合适的位置？
+- 是否尽可能复用已有实现？
+- 是否有破坏现有设计与逻辑的可能？
+
+### 3. Bug 检查
+
+- 是否隐含业务错误、逻辑纰漏或安全问题？
+- **未修改**的相关联代码是否有遗漏？
+
+### 4. 代码清晰度
+
+- 逻辑是否简洁易懂？
+- 命名是否清晰合理？
+- 一年后再读，是否能轻松理解？
+
+### 5. KISS 原则
+
+- 是否有不必要的复杂度？
+- 是否有未使用的定义、过多参数？
+- 是否重复造轮子？
+
+### 6. 单一职责
+
+- 每个函数/类是否只做一件事？
+- 文件/类/方法行数是否合理？
+
+### 7. 测试覆盖
+
+- 复杂业务逻辑（含 if/else/for）是否有测试？
+- 测试是否有效（非空实现）？
+- 不应过度测试无控制逻辑的代码。
+
+## 输出
+
+评审完成后，总结发现的**重点问题**，按严重性排列。
+
+## AI 与人工的分工
+
+| 维度 | 负责方 | 说明 |
+| ---- | ------ | ---- |
+| Bug、逻辑漏洞、安全问题 | **AI + 人工** | AI 负责初筛与证据收集，结论需人工复核 |
+| 代码清晰度、KISS、单一职责 | **AI + 人工** | AI 提供候选问题，人工决定是否采纳 |
+| 架构合理性、业务对齐 | **人工** | AI 反馈少且准确率低，需人工把关 |
+| 兼容性、历史债务、战略取舍 | **人工** | 依赖背景知识，AI 难以判断 |
+
+> 规则：AI 结论必须附文件路径、行号或可复现依据；缺少证据时按待确认假设处理。
+>
+> 注意：评审不只看 diff，需结合代码库整体上下文做评估。

tests/README.md

@@ -11,6 +11,7 @@ tests/
 │   └── test_playbook_cli.py        # playbook.py 基础功能测试
 ├── test_format_md_action.py        # format_md 动作测试
 ├── test_gitattributes_modes.py     # gitattr_mode 行为测试
+├── test_no_backup_flags.py         # no_backup 行为测试
 ├── test_sync_directory_actions.py  # sync_memory_bank/sync_prompts 行为测试
 ├── test_vendor_snapshot_templates.py # vendor 快照模板完整性测试
 ├── test_plan_progress_cli.py       # plan_progress CLI 测试

tests/templates/validate_project_templates.sh

@@ -91,6 +91,7 @@ validate_file_exists "$PROMPTS_DIR/README.md" "prompts/README.md"
 validate_file_exists "$PROMPTS_DIR/system/agent-behavior.template.md" "prompts/system/agent-behavior.template.md"
 validate_file_exists "$PROMPTS_DIR/coding/clarify.template.md" "prompts/coding/clarify.template.md"
 validate_file_exists "$PROMPTS_DIR/coding/review.template.md" "prompts/coding/review.template.md"
+validate_file_exists "$PROMPTS_DIR/coding/code-review.template.md" "prompts/coding/code-review.template.md"
 validate_file_exists "$PROMPTS_DIR/meta/prompt-generator.template.md" "prompts/meta/prompt-generator.template.md"
 
 echo ""