agent-infra - AI 开发指南

本仓库包含 agent-infra 模板和技能仓库，用于多 AI 协作基础设施。

AI 行为准则（必须遵守）

源自 Andrej Karpathy 总结的 4 条 LLM 编程铁律，本项目所有 AI 工具均需遵守。 与下方项目规范冲突时，以项目规范为准；其余场景以本节为准。 这些准则偏向「稳」而非「快」，琐碎任务可酌情判断。

SKILL 执行场景的特例：在执行任一 SKILL 时，优先遵循 .agents/rules/no-mid-flow-questions.md（默认禁言 + 该规则文件列出的例外）。每次执行 SKILL 前应先 Read 该规则文件，以加载完整例外清单和具体约束。这与下文第 1 条「不确定就提问」不矛盾——SKILL 执行有明确的输入、输出和产物，不确定项应按最稳健方案推进并写入产物的「假设」/「未决问题」段落，由用户在审查检查点统一处理，而不是中途打断对话。

1. 先思考，再动手（Think Before Coding）

不要硬猜，不要藏起困惑，把权衡点摆到台面上。

• 在 SKILL 执行期间，先按 .agents/rules/no-mid-flow-questions.md 的诊断与恢复顺序处理工具和执行问题；把仍未解决的假设或问题写入产物。
• 对 SKILL 入口的自然语言需求，若存在会实质影响范围的歧义且不能从已有事实安全推导，再按对应入口规则澄清。
• 对可逆、低影响的执行细节，优先采用符合现有代码和规则的方案并说明假设，不为一般执行选择中断工作流。
• 当平台、客户端、协议、工作流、业务规则或算法存在多种行为时，识别各实现共用的流程，并用接口定义可替换的行为；主流程依赖接口，具体策略在注册或装配处选择。新增变体优先实现策略并接入现有装配逻辑，避免给每条链路分别增加分支。方案和实现阶段遵循 .agents/rules/strategy-pattern.md。
• 有更简单的方案就说出来，必要时反推用户的决定。
• 需要用户独有的事实或授权、无法验证安全边界或无法安全恢复时，按适用规则升级；其余情况继续独立工作并记录阻塞条件。

2. 简洁优先（Simplicity First）

选择能正确承载需求与真实变化的最简设计，不以最少行数或最少抽象为目标。

• 不添加未被要求的功能、配置项或缺乏行为差异依据的抽象。为已明确的不同实现定义接口属于正确设计，不是投机扩展。
• 不为稳定、单一且没有明确变化迹象的逻辑引入抽象层；当需求包含真实的行为变体时，应使用接口和策略模式隔离差异，即使当前只有一个实现。
• 不为不可能发生的场景写错误处理。
• 写了 200 行但 50 行就够时，重写它。
• 自检："资深工程师会觉得这过度设计吗？"——会，就简化。

兼容性默认关闭（Compatibility by Exception）

没有明确兼容承诺时，只实现当前契约，不主动保留旧行为。

• 不因“可能有旧调用方”而新增 adapter、wrapper、shim、双写、旧 schema 读取或迁移分支。
• 兼容性必须有证据：明确的旧消费者或存量数据、不可直接切换的原因、支持期限和删除条件；缺少任一项时按当前版本直接切换。
• 优先一次性边界迁移或可操作的失败提示，不在主路径长期维护新旧两套状态机。
• 临时兼容集中在唯一边界，并在该边界用 TODO(compat): Remove ... once ... 标记删除对象和可验证删除条件；任务或 Issue 仅用于可选排期，不是兼容事实源或完成门禁。
• 当前流程的崩溃恢复、幂等重试和安全校验不等于历史兼容；只保留证明当前操作正确所需的最小事实。
• 发现任务范围外的既有兼容逻辑时只记录，不顺手删除；新增或延长兼容逻辑则必须遵循 .agents/rules/compatibility-policy.md。

3. 外科手术式修改（Surgical Changes）

只动该动的地方；只清理你自己制造的垃圾。

• 不顺手"优化"邻近代码、注释、格式。
• 不重构没坏的东西。
• 保持现有风格，即使你个人偏好不同。
• 发现无关的死代码——提醒用户，不要擅自删除。
• 因你的改动而产生的孤儿 import/变量/函数，必须由你清理。
• 自检：每一行改动都能直接追溯到用户的请求吗？

4. 目标驱动执行（Goal-Driven Execution）

先定义可验证的成功标准，再循环执行直到达成。

把任务转成可验证的目标：

• "加校验" → "先写非法输入的失败用例，再让它通过"
• "修 Bug" → "先写复现该 Bug 的用例，再修到通过"
• "重构 X" → "确保重构前后测试都通过"

多步任务先列计划，每一步都附带 verify 检查点：

1. [步骤] → verify: [检查项]
2. [步骤] → verify: [检查项]
3. [步骤] → verify: [检查项]

强成功标准让你能独立闭环；弱标准（"让它跑起来"）会让用户不断澄清。

这套准则生效的迹象：diff 中不必要的改动变少；因过度设计被推翻重写的次数变少；澄清问题发生在动手之前而不是踩坑之后。

上下文压缩规则（必须遵守）

当上下文窗口接近上限、需要对历史消息做有损压缩时，按以下优先级保留 / 丢弃信息。 本节约束 LLM 自身的压缩行为，不属于「项目规范」范畴，与上文 AI 行为准则并列、不冲突。

压缩时必须保留

• 任务上下文：当前 task-id、关联 Issue/PR 号、current_step、最近一次 SKILL 产物文件名（如 analysis-r2.md、plan.md）。
• 用户偏好与显式 feedback：被告知「不要这样做」/「一直这样做」的指令、memory 风格的偏好声明。
• 不可逆 / 已发布的副作用：已执行的破坏性操作（rm -rf、git push --force、gh issue edit 等）、跨轮次的设计决策与裁决理由。
• 未结清的失败信号：未确认的报错栈、用户尚未回应的提问、被挂起的未决问题。

压缩时可有损摘要

• 已成功完成且无后续依赖的工具调用原始输出（可改为「已读取 X / 已写入 Y」摘要）。
• 中间草稿与未被采纳的方案。

压缩时的自检

• 压缩后能否独立续写当前 SKILL？若不能，说明保留不足，应回补。
• 是否丢失了任何远端副作用或用户偏好？若是，必须回补。

快速开始命令

# 安装依赖：开发检出后必须先安装真实 npm 依赖
npm install

# 构建项目：编译 TypeScript 源文件到 dist/
npm run build

# 运行测试
npm test

# 代码检查：暂未配置 lint 工具

编码规范（必须遵守）

• install.sh 保持 POSIX sh 兼容，使用 set -e 进行错误处理
• 模板文件使用 {{project}} 和 {{org}} 作为渲染占位符
• Markdown 文件提供双语版本（英文为主 + 中文翻译）

版权头更新规则

修改任意带版权头的文件时，必须更新版权年份：

1. 先运行 date +%Y 获取当前年份（不要硬编码）
2. 更新格式示例（假设当前年份为 2026）：
   • 2024-2025 -> 2024-2026
   • 2024 -> 2024-2026

分支命名

使用项目前缀：agent-infra-feature-xxx、agent-infra-bugfix-yyy

项目结构

├── bin/                           # CLI 可执行文件
│   └── cli.ts                     # 主 CLI TypeScript 源文件
├── .agents/                       # AI 协作配置与工作区
│   ├── .airc.json                 # 项目配置
│   ├── workspace/                 # 任务工作区
│   ├── skills/                    # 技能仓库
│   └── workflows/                 # 工作流定义
├── templates/                     # 模板源文件（镜像项目目录结构）
├── tests/                         # 测试（Node.js 内置测试运行器）
├── install.sh                     # 引导安装脚本
└── package.json                   # npm 测试脚本定义

测试要求

• 测试框架：Node.js 内置测试运行器（node:test，需 Node.js >= 22.9.0）
• 运行命令：npm test
• 测试覆盖：模板文件完整性、CLI 初始化流程、占位符渲染验证

TypeScript 规范

• 项目源码使用 TypeScript 编写，通过 tsc 编译到 dist/ 后发布；运行时要求 Node.js >= 22.9.0。开发态可直接 node --experimental-strip-types ./bin/cli.ts。
• TypeScript 只使用 erasable syntax：禁止 enum、值级 namespace、class 参数属性、装饰器、import = 和 export =。
• ESM 相对 import 在源码中继续写 .ts 后缀，tsc 通过 rewriteRelativeImportExtensions 输出 .js 后缀到 dist/。

测试编写规约

1. 禁止关键词语义断言：不要通过匹配自然语言措辞来验证 skill 文档内容（如 assert.match(content, /某段具体描述/)）。SKILL.md 的文案会频繁调整，绑定措辞的测试极其脆弱。只做结构性检查：frontmatter 合法性、步骤编号连续、引用完整性、体积阈值等。
2. 禁止反向删除断言：已删除的功能不需要断言其不存在（如 assert.doesNotMatch(content, /removedField/)）。删除即彻底删除，不要用测试永久记住一个不再存在的概念，否则会形成无止境的测试债务。
3. 平台守卫只走 helper：跨平台测试的「整条是否运行」判定必须通过 tests/helpers.ts 的 onPlatforms() 表达，不得在测试体内写 if (process.platform === ...) return; 早返回。同测试体内覆盖多平台行为差异（断言/构造分支）、运行时回退（如 EPERM）属于合法用例。详见 .agents/rules/cross-platform-tests.md。

正反例（含正向/反向断言取舍）详见 .agents/rules/testing-discipline.md。

提交与 PR 规范

详见 .agents/rules/commit-and-pr.md（提交代码或创建 PR 时按需加载）。

安全注意事项

• 不要提交敏感文件：.env, credentials.json, 密钥等
• 安全问题请按 SECURITY.md 指引私下提交（不要公开 Issue）

多 AI 协作支持

本项目支持 Claude Code、Codex、Antigravity CLI、OpenCode 等多个 AI 工具协同工作。

协作配置目录：

• .agents/ - AI 配置和工作流定义（版本控制）

协作指南：.agents/README.md

Skill 维护强制要求：

• 修改或新增 .agents/skills/*/SKILL.md 及其模板前，必须先读取 .agents/README.md 中的 “Skill 编写规范” 和 “SKILL.md 体积控制” 章节。

语言规范

项目代码层面统一使用英文，文档提供多语言版本（英文为主版本）。 未在下表中列出的场景，默认使用中文。

中文技术写作规范

本节适用于面向人的中文项目文档和 AI 的中文回复；不适用于代码、命令、日志、引用内容、API 名称和已定义的专业术语。英文文档不机械翻译本节规则。

• 句子应说明明确的主体、动作、对象和必要条件。信息不足时，直接说明缺少的信息，不用套话填充篇幅。
• 只在确有因果、转折或递进关系时使用“但是”“因此”“同时”等连词，不为连接句子而添加连词。
• 不使用比喻、拟人、肢体动作式表达描述抽象概念；已经定义的专业用语不受此限。
• 不使用下列夸大或空泛的职场用语：赋能、抓手、颗粒度、沉淀、打法、势能、生态位、顶层设计、全链路、底层逻辑、拉齐、打通、对标、勾兑、倒逼、引爆点。
• 不使用无指向的代词或名词：东西、那一套、一个形状、这种感觉、那么回事。改用实际对象，例如产物、改动、材料、问题、来源、配置或数据。
• 不使用对象不明的万能动词，例如“走”“打”。改用执行、调用、创建、发送、读取、写入、比较或删除等具体动词。
• “不是 A 而是 B”仅在 A 有明确出处且该对比有助于理解时使用。
• 优先使用简短的现代技术书面语；不模仿文言文，不使用网络口语，不用总结性口号替代事实。

提交代码或创建 PR 时，必须先读取 .agents/rules/commit-and-pr.md。 执行任务工作流命令时，必须先读取 .agents/rules/task-management.md。 不确定该加载哪篇规则时，先查阅 .agents/rules/README.md 规则索引（按业务域列出全部规则及其用途）。