0552180e45
- CONVENTIONS.md v1.8.0：蓝图定位为意图层，files 字段变可选，status/progress 从 git 推断 - 新增 agent-infrastructure 模块（concept）：接入包 v2，扫描→确认→生成三件套 - AGENTS.md.tmpl 注入四支柱 + T1-T4 防腐元规则 - 炼境自身接入自己的包：AGENTS.md + docs/ai-context/ + .claude/rules/ - docs/templates/ 三件套模板：agents-meta-rules / project-brief / project-context
2.8 KiB
2.8 KiB
| version | updated | usage |
|---|---|---|
| 1.0.0 | 2026-06-29 | 炼境接入包分发时写入被管理项目 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的契约路径还准确吗？