dev-manager-tauri/docs/templates/agents-meta-rules.md

version	updated	usage
1.1.0	2026-07-03	炼境接入包分发时写入被管理项目 AGENTS.md 的元规则标准内容

Agent 友好工程元规则

本节由炼境接入包分发，规则技术栈无关，适用于所有项目和所有 AI 工具。 项目特定的路径映射见 docs/ai-context/project-context.yaml。

---

Agent 友好工程四支柱

修改代码前，确认这个项目满足四支柱：

可导航：凭文件名/目录名可在 30 秒内定位某功能的代码。通用能力有独立家，不寄生在业务模块下。

可推理：公共类型只在一处定义。改一个接口，类型检查能报出所有受影响处。

可验证：typecheck / lint / test 各有一条命令真能跑。关键路径有冒烟测试。

可记忆：规则按场景注入（不是一份巨型文档）。决策只写"为什么"，代码自己回答"是什么"。

---

文档防腐元规则

做任何改动时，判断它属于哪类变更：

T1 外部契约变更（最高优先级）

其他代码、服务、或 agent 依赖的定义——接口、共享类型、数据结构、配置键名、环境变量名。 → 查 docs/ai-context/project-context.yaml 找到记录该契约的文档，检查并同步更新。

T2 架构边界变更

模块划分、目录结构、依赖方向、包边界调整。 → 检查架构文档是否需要同步。

T3 工具链变更

引入或替换库、框架、构建工具。 → 更新 AGENTS.md 技术栈声明；通知炼境重新扫描并更新 project-context.yaml。

T4 常驻上下文过期

AGENTS.md 或 docs/ai-context/project-brief.md 描述的现实已经改变。 → 立即更新。这两份文档常驻 agent 上下文，过期危害最大。

不触发检查

内部重构、性能优化、bug fix（外部行为不变）、测试文件、临时脚本。

---

文档防腐铁律

• 文档只写稳定的：为什么、铁律、意图、架构决策。
• 易变的（端口、路由、表名、命令清单）交给工具自省，不写死进常驻文档。写死 = 定时炸弹。
• 单一事实来源：两处说同一事时，删掉派生的那处。
• 两份文档打架时，信代码，不信文档。

---

跨 AI 工具交接模板

完成一段工作并交接给下一个 agent 时，附上：

已完成：<修改了哪些文件 + 核心决策>
待验证：<需要对方确认的地方>
约束继承：<影响对方工作的关键限制>

---

定期防腐自查

每隔一阵或大改后，对照以下清单：

• AGENTS.md 里的技术栈声明还和代码一致吗？
• project-brief.md 最近 30 天有没有随架构改动更新？
• 有没有两份文档说同一件事且打架？
• project-context.yaml 的契约路径还准确吗？

---

Agent 按钮体系

让 AI agent 具备无人值守执行能力的工程方针。随炼境接入包分发，适用于所有项目和所有 AI 工具。

分工原则

人定目标 → agent执行 → agent自验（走agent按钮） → 人终验

人只保留两件事：需求澄清（目标定义权） 和 目标验收（终验权）。中间的执行与验证环路在 agent 内部闭合。

Agent 按钮清单（接入时必填）

在项目 AGENTS.md 中声明本项目的 agent 按钮，让 agent 知道有哪些能力可调用：

## Agent 按钮（可调用能力）
| 能力 | 调用方式 | 通过标准 |
|------|---------|---------|
| 类型检查 | `<填入命令>` | `<填入通过标准>` |
| 测试运行 | `<填入命令>` | `<填入通过标准>` |
| 核心功能验证 | `<填入命令>` | `<填入通过标准>` |

三要素缺一不可：可发现（清单里有）、可调用（结构化命令）、边界清晰（通过标准明确）。

Acceptance 写法规范

acceptance 是 agent 自验的唯一判断依据，必须是可执行断言，不能是描述性语句：

❌ "功能正常运行"（描述性，agent 无法判断完成）
❌ "代码正确"（主观，无可执行路径）
✅ "pnpm test 通过"
✅ "curl /api/xxx 返回 200，body.id 非空"
✅ "pnpm typecheck 无报错"
✅ "[命令] 运行什么 → 断言什么"

含 acceptance 的任务卡才可派发；acceptance 可执行，自验才是真自验——这是整个体系的核心关节。

自验失败降级约定

• 失败 2 次内：自行修正，继续自验
• 失败 3 次：停止执行，输出以下内容后等待人工介入：
  1. 失败原因（具体报错或不通过的断言）
  2. 已尝试的修正路径
  3. 需要人决策的具体问题

无人值守不是消灭人工介入，而是把人从"执行路径"移到"降级路径"。降级时主动升级，比静默卡死更重要。