7907793f19
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
9.8 KiB
| version | aligned_with | updated | usage |
|---|---|---|---|
| 1.10.0 | src-tauri/resources/onboarding/AGENTS.md.tmpl ONBOARDING_MANAGED 1.10.0 | 2026-10-04 | 炼境接入包分发时写入被管理项目 AGENTS.md 的元规则标准内容 |
Agent 友好工程元规则
本节由炼境接入包分发，规则技术栈无关，适用于所有项目和所有 AI 工具。 项目特定的路径映射见
docs/ai-context/project-context.yaml。
与分发模板的对照（ONBOARDING_MANAGED 1.10.0，2026-10-04 逐节核对）
分发实体是 src-tauri/resources/onboarding/AGENTS.md.tmpl，措辞以模板为准；本文件是设计层，补「为什么」，不重复模板全文。
| 模板小节（托管块内） | 本文件 | 差异 |
|---|---|---|
| 核心开发约束（包管理、代码规范、Playwright 版本固定） | 无 | 不复制，以模板为准 |
| 需求对齐协议（Bug/Feature 分流、S 级三行卡、M/L 完整卡、Feature-Confirmed、补录≠确认卡） | 无 | 不复制，以模板为准 |
| Git 工作流（git-workflow.md、Conventional Commits） | 无 | 不复制，以模板为准 |
| 炼境项目上下文与能力包 | 同名小节 | 五条已同步为模板原文；Node/pnpm 工具链小节只留指针 |
| agent 按钮与验证路径（1–6 条 + 收束） | 「Agent 按钮体系」 | 本文件有同源同边界、acceptance 写法、自验报告纪律及其「为什么」；缺载体就近选择表、完成的定义、侦察→驻军、agent_verify/human_verify 分层与三分定位启发式（以模板为准）；本文件多出的分工原则、按钮清单模板、自验失败降级约定已不在托管块内（炼境自身见 AGENTS.md 块外区） |
| 多 AI CLI 协作 | 「跨 AI 工具交接模板」 | 内容等价，模板为编号三条 |
| 模板小节（托管块外） | 本文件 | 差异 |
|---|---|---|
| 四支柱、文档防腐 T1–T4、铁律、定期防腐自查 | 同名小节 | 已同步：T1 补「（若存在）」、T3/T4 改指「本文件（AGENTS.md）」、自查路径写全 docs/ai-context/ |
炼境项目上下文与能力包
.lian-jing/context.json是项目project_id的工具无关单一事实来源；不要从客户端项目 UI、用户级插件或全局配置推断项目身份。.claude/liangjing.json只是旧项目的 Claude 兼容投影。只发现它时，调用inject_mcp(project_id)迁移，而不是手工复制或猜测 ID。.lian-jing/capability-packs.json记录炼境托管基线的版本。verify_onboarding(project_id)报告legacy、version_mismatch等状态时，按其detail中的升级提示处理。apply_onboarding_pack(project_id)只更新炼境明确托管的接入包文件；项目自己的业务规则、测试、部署声明和手工定义的同名 MCP server 仍归项目所有，不能被升级覆盖。- 遇到炼境分发的模板、约定或 MCP 工具的摩擦，或验证出跨项目可复用的实践时，调用
report_envoy_return回传炼境（只追加信号，不必逐条征得用户同意；Claude 会话结束时也可跑/envoy）；何时回传、字段怎么填见 lian-jing skill「遇到摩擦时回传炼境」一节。
Node/pnpm 工具链
见模板同名小节（.nvmrc / packageManager 为版本事实源、mise 最小声明、get_toolchain_status 先查、prepare_toolchain 须用户确认）；措辞以模板为准。
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 里的技术栈声明还和代码一致吗？
docs/ai-context/project-brief.md最近 30 天有没有随架构改动更新？- 有没有两份文档说同一件事且打架？
docs/ai-context/project-context.yaml的契约路径还准确吗？
Agent 按钮体系
让 AI agent 具备无人值守执行能力的工程方针。随炼境接入包分发，适用于所有项目和所有 AI 工具。
分工原则
人定目标 → agent执行 → agent自验（走agent按钮） → 人终验
人只保留两件事：需求澄清（目标定义权） 和 目标验收（终验权）。中间的执行与验证环路在 agent 内部闭合。
Agent 按钮清单（接入时必填）
在项目 AGENTS.md 中声明本项目的 agent 按钮，让 agent 知道有哪些能力可调用：
## Agent 按钮（可调用能力）
| 能力 | 调用方式 | 通过标准 |
|------|---------|---------|
| 类型检查 | `<填入命令>` | `<填入通过标准>` |
| 测试运行 | `<填入命令>` | `<填入通过标准>` |
| 核心功能验证 | `<填入命令>` | `<填入通过标准>` |
三要素缺一不可：可发现（清单里有）、可调用（结构化命令）、边界清晰（通过标准明确）。
同源同边界（设计原则，v1.7.0 起）
任何功能 = 一个本体 + 两个投影：本体是能力层实现（API/command/服务函数），人按钮（UI）与 agent 按钮都是它的投影。同源 = 两投影走同一代码路径；同边界 = 业务校验只在本体层砌一次墙。设计交付时先定本体后盖投影（原型探索豁免此序，交付前本体归位）。
同源的直接推论：人的操作序列 agent 皆可复刻——人报障即复现路径（操作 + 状态），agent 重放至同一状态定位病灶。三分定位启发式：本体重放正常 → 优先怀疑投影层 → 再查环境差异；重放失败先怀疑初始状态差异，而非否定问题存在。
效果分两层：防御——人指的问题即复现路径，agent 走得到；进攻——操作成为人机共同语言，人的验收反馈天然绑定双方走过的路径，需求信息对称。对称有两个时间尺度：当下会话由同源结构直接保证（无需额外机制）；跨会话需反馈落账（human_verify 否决理由 → 复盘笔记 → 梦核蒸馏），人反复在意的维度逐步迁移为可断言规则——人裁决区是飞轮推进的前线，不是墙上的洞。
收束：本体先行，边界一次，操作同语——人指的问题 agent 走得到，人在意的点 agent 读得懂。
Acceptance 写法规范
acceptance 是 agent 自验的唯一判断依据，必须是可执行断言，不能是描述性语句：
❌ "功能正常运行"（描述性，agent 无法判断完成）
❌ "代码正确"（主观，无可执行路径）
✅ "pnpm test 通过"
✅ "curl /api/xxx 返回 200，body.id 非空"
✅ "pnpm typecheck 无报错"
✅ "[命令] 运行什么 → 断言什么"
含 acceptance 的任务卡才可派发；acceptance 可执行，自验才是真自验——这是整个体系的核心关节。
自验报告纪律
- 交人终验前的反馈必须含「没验什么」一节：未覆盖的路径、依赖的假设、不确定的地方
- 自修过程中改了断言/验收标准必须显式声明理由（改功能让测试过是常规，改测试让功能过需报备）
- agent 自验对 acceptance，人终验对意图——acceptance 可能继承需求理解偏差，两把尺子不可合一
为什么：自验的结构性盲区是"验证代码与功能代码共享同一份理解偏差"，负面披露收窄已知盲区， 人终验（对意图、带意外感触发的深查）兜底未知盲区。两者互补，缺一另一超载。
自验失败降级约定
- 失败 2 次内：自行修正，继续自验
- 失败 3 次：停止执行，输出以下内容后等待人工介入：
- 失败原因（具体报错或不通过的断言）
- 已尝试的修正路径
- 需要人决策的具体问题
无人值守不是消灭人工介入，而是把人从"执行路径"移到"降级路径"。降级时主动升级，比静默卡死更重要。