9.2 KiB

Raw Blame History

AGENT_RULES

目的：为本仓库提供稳定的执行流程与行为规范。

优先级

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

安全红线

不得在代码/日志/注释中写入明文密钥、密码、Token
修改鉴权/权限逻辑必须说明动机与风险
不确定是否敏感时按敏感信息处理
执行修改文件系统的命令前，必须解释目的和潜在影响

行为准则

项目适应

模仿项目风格：优先分析周围代码和配置，遵循现有约定
不假设可用性：不假设库或框架可用，先验证再使用
完整完成请求：不遗漏用户要求的任何部分

技术态度

准确性优先：技术准确性优先于迎合用户
诚实纠正：发现用户理解有误时，礼貌纠正
先查后答：不确定时先调查再回答

避免过度工程

只做要求的：不主动添加未要求的功能或重构
不过度抽象：不为一次性操作创建工具函数
不为未来设计：不为假设的未来需求设计

沟通原则

统一简体中文：所有回复均使用简体中文
简洁直接：专业、直接、简洁，避免对话填充词
拒绝时提供替代：无法满足请求时，简洁说明并提供替代方案
不给时间估算：专注任务本身，让用户自己判断时间
代码块标注语言：输出代码时标注语言类型
不使用 emoji：除非用户明确要求

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

必读文档（按顺序）：

AGENT_RULES.local.md - 项目私有规则（如存在，优先级高于本文件）
.agents/index.md - 语言规则入口（如存在）
memory-bank/project-brief.md - 项目定位、边界、约束
memory-bank/tech-stack.md - 技术栈、工具链
memory-bank/architecture.md - 架构设计、模块职责
memory-bank/decisions.md - 重要决策记录（如存在）
memory-bank/progress.md - 执行进度与状态（如存在）
docs/plans/ - 最新实施计划（如存在）

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

规划与执行分工

阶段	工具	产出	留痕
头脑风暴	`$brainstorming` skill	设计思路	无
生成计划	`$writing-plans` skill	`docs/plans/*.md`	无
执行计划	主循环	代码/配置变更	plan_progress.py

重要：第三方 skills 不记录操作状态，执行必须通过主循环完成。

主循环

触发词：

触发词	模式	说明
`执行主循环`、`继续执行`、`下一个 Plan`	常规模式	遇确认场景可询问用户
`自动执行所有 Plan`	无交互模式	不询问，按规则自动处理

Plan 状态：

状态	含义
pending	待执行
in-progress	执行中（崩溃恢复用）
done	已完成
blocked	阻塞（需人工介入）
skipped	跳过（Plan 不再需要执行）

说明：skipped 仅用于永久不再执行；如需恢复执行，需手动改回 pending。

环境阻塞格式：blocked: env:<环境>:<Task列表>

示例：blocked: env:windows:Task2,Task4
含义：需要在指定环境执行列出的 Task
约束：Task 列表使用英文逗号分隔，不要包含空格，便于解析

流程：

检测环境：
- 由 plan_progress.py 自动识别当前环境（windows / linux / darwin）
选择 Plan：
- 运行 python docs/standards/playbook/scripts/plan_progress.py select -plans docs/plans -progress memory-bank/progress.md
- 返回第一个可执行的 Plan：
  - pending 或 in-progress 的 Plan
  - blocked: env:<当前环境>:... 的 Plan（环境匹配时恢复执行）
- 如无可执行 Plan，跳到步骤 7
- 注意：每次 select 会重新扫描 docs/plans/ 目录，支持动态添加 Plan
标记开始：
- 运行 python docs/standards/playbook/scripts/plan_progress.py record -plan <plan> -status in-progress -progress memory-bank/progress.md
阅读 Plan：
- 理解目标、子任务与验证标准
- 如果是从 blocked: env:... 恢复，只执行列出的 Task
逐步执行：
- 按顺序执行 Task
- 每个 Task 完成后进行必要验证（测试/日志/diff）
- Task 失败处理：
  - 环境不匹配（command not found、路径不存在）→ 记录该 Task 及所需环境，继续下一个 Task
  - 其他阻塞 → 记录原因，跳到步骤 6 标记 Plan blocked
- 安全红线（明文密钥等）→ 立即停止，不继续后续 Plan
- 遇到歧义/风险/决策点：
  - 常规模式：记录到回复中，可询问用户
  - 无交互模式：按「需要确认的场景」规则自动处理
记录结果：
- 全部完成：... -status done ...
- 有 Task 因环境跳过：... -status blocked ... -note "env:<所需环境>:<Task列表>"
- 其他阻塞：... -status blocked ... -note "<原因>"
- 跳过整个 Plan：... -status skipped ... -note "<原因>"
- 回到步骤 2 继续下一个 Plan
汇总报告（所有 Plan 处理完毕后）：
- 已完成的 Plan
- 阻塞/跳过的 Plan 及原因
- 需要在其他环境执行的 Plan（blocked: env:...）
- 待确认的歧义/风险/决策点
- 如需记录重要决策，写入 memory-bank/decisions.md
结束：主循环终止

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
小步快跑：每个 Plan 应该可快速完成
可验证：每个 Plan 必须包含验证步骤

执行约束

代码修改

必须先读文件再修改：不读文件就提议修改是禁止的
必须运行测试验证：相关测试必须通过
遵循换行规则：遵循 .gitattributes 规则
命名一致性：遵循项目现有的命名风格
最小改动原则：只修改必要的部分，不顺手重构

决策记录

重要决策：记录到 memory-bank/decisions.md（ADR 格式）
待确认事项：在回复中列出并等待确认
进度留痕：通过 docs/standards/playbook/scripts/plan_progress.py 维护 memory-bank/progress.md 的 Plan 状态块（唯一权威）

Git 操作

不使用 --amend：除非用户明确要求，总是创建新提交
不使用 --force：特别是推送到 main/master，如用户要求必须警告风险
不跳过 hooks：不使用 --no-verify

工具使用

并行执行：独立的工具调用尽可能并行执行
遵循 schema：严格遵循工具参数定义
避免循环：避免重复调用同一工具获取相同信息
优先专用工具：文件操作用 Read/Edit/Write，搜索用 Grep/Glob

需要确认的场景

常规模式（可交互）：

需求不明确或存在多种可行方案
需要行为/兼容性取舍
风险或约束冲突
架构变更：影响多个模块的修改
性能权衡：需要在性能和可维护性之间选择
兼容性问题：可能破坏现有用户代码

无交互模式（自动处理）：

场景	处理方式
安全红线	立即停止，不继续后续 Plan
架构变更/兼容性/破坏性修改	标记 blocked，跳到下一个 Plan
多种可行方案	选择最保守方案，记录选择理由到报告
歧义/风险/决策点	记录到报告，继续执行

可以不确认（两种模式通用）：

明显的 bug 修复
符合现有模式的小改动
测试用例补充

验证清单

每个 Plan 完成后，必须验证：

代码修改符合 .agents/ 下的规则（如有）
相关测试通过（如有测试且未被豁免）
换行符正确
无语法错误
已通过 plan_progress.py 记录 Plan 状态

最后更新：2026-02-03

9.2 KiB Raw Blame History Unescape Escape