AGENTS.md — 编码规范

让 AI 编程 Agent 别像个实习生什么都想自己造，要像个干了十年的老油条一样写代码。

内容规则入口

有本仓库读取权限的 agent 从 README.md 读取、安装或更新三套独立规则。按任务涉及范围分别调用：

• 隐私与凭据脱敏：privacy-redaction。
• 成人内容公开可见性及私密库名：nsfw-output-guard。
• 用户敏感词格式及禁读输入：sensitive-words-guard。

三份文件是唯一原文；本机技能目录通过链接接入。仓库访问权限不解除禁读输入和私有报告的限制；检查不可用或失败时不得声称通过。

项目设计共同约定（所有 Agent / Harness）

新建项目、重构或技术选型前，读取 项目设计共同约定。用户要求：轻量化、模块化、插件化、尽量解耦，尽量分离为不同的项目组合在一起。优先独立职责、明确接口与薄编排层；避免无必要的服务拆分和预防性抽象。详细原则以链接文件单源维护。

本文件是本知识库的项目行为入口；仅在 index 添加链接不代表规则已被加载。其他工作目录中的 Harness 需要在自身原生指导入口引用本约定；不要假定所有工具自动读取本库或自动跟随链接。

所有 Web 项目的主题参考

新建或重构 Web 服务和网页时，先读取 aform theme（aform 主题）共享入口，按 ${DATA_ROOT}/dev/aform 的设计与接入文档统一导航、主题、控件和交互，各项目保留自己的业务页面、数据、仓库与部署。主题持续在独立项目维护，各站固定版本并分别升级验收；本入口不代表已有项目已经迁移。

工作留痕与交接（所有 Agent / Harness）

涉及实际改动、可复用知识或长任务交接时，在 d/a 对应项目/主题文档留下总结，记录目标、关键决策、实际改动、验证结果、当前状态及证据/产物位置；优先补充已有文档，不为每条问候或无长期价值的简单问答另建文件。用户明确只读时不写留痕；不把计划或未验证结果写成已完成。

长任务在阶段节点、暂停、中断、换 agent 或存在未完成事项时，适时更新 handoff：写清已完成/未完成、卡点、相关文件与运行状态、复跑/验证方法及建议下一步，让接手者不必重新翻聊天或重复调查。接手前先读最新留痕和 handoff，再核对真实现状。

留痕是知识总结，不是原始资料倾倒：未经总结吸收的 session、对话备份、日志及原始报告放在 d/ai，d/a 仅保留安全摘要与必要引用；不写入凭据、私有映射或禁读内容。新增文档接入现有索引，不因留痕擅自提交其他人的改动或推送。

核心规则

授权按当前任务范围解释：明确只读时不写文件；已授权可逆维护自行完成，删除/迁移先读内容并备份，超范围或必要安全门禁仍需确认。默认当前 agent 自做，管理其他 agent 配置不等于委派授权。模型目录更新不自动改变默认模型、provider 或凭据；default profile 未重新授权不纳入舰队变更。

1. 移除经验证无用的兼容负担，不为假想需求堆代码。 数据迁移、必要的升级兼容和生产故障回退不在禁用范围；删除前按授权备份，不能以精简破坏数据或可恢复性。
2. 选能满足当前需求的最简单实现。 不要预防性抽象，不要多此一举的配置层。
3. 系统分层长。 先跑通一个最小的端到端版本，再往上加东西。绝不为了未完成的复杂度拆掉能跑的东西。
4. 组件保持模块化，关注点分离。
5. 优先用成熟的、有人维护的库。 没有明确理由别自己重写。
6. 先翻项目里已有的依赖能做什么，再考虑加新包或自己写。 别上来就假设库里没有。
7. 架构决策往长了做。 不接受”先这样以后再换”的临时方案。
8. 先看成熟产品怎么解决同一个问题，用已验证的模式，别从零发明。
9. 新项目或重大技术选型先查已有实现与成熟产品。 优先复用本机现有项目和依赖，必要时再查维护中的开源方案；需新增依赖、架构或授权范围时给最小方案并确认。已明确授权的修复、配置维护与小改动直接实施验收，不为每次改动重复做选型或索取确认。

---

来源：小红书 ArchGenAI《AGENTS.md 让 AI 通过率 100%》

Agent 专用 GitHub 账号

Agent 管理项目默认使用 ainit0：~/.local/bin/gh-agent、~/.local/bin/git-agent。GitHub 操作读取 github-agent，首次远端写入前用 gh-agent api user --jq .login 核对身份。普通 gh 和 ChatGPT GitHub connector 的个人账号保持独立；已有仓库遵循其 owner/remote，不自动迁移。