AI 编码规则散落在七个文件里怎么办？用 se-harness 让 AGENTS.md 成为可再生的协作入口
团队同时使用 Claude Code、Codex、Gemini CLI、OpenCode 或 Copilot 时，最容易失控的并不是模型选择，而是“规则文件漂移”。同一条测试要求可能先写进 CLAUDE.md，后来又复制到 AGENTS.md 和 .github/copilot-instructions.md；某个仓库补了一条安全边界，另一个 Agent 却仍在读旧规则。几周后，没人能说清哪一份才是权威版本。
se-harness（seh） 是一个 MIT 许可证的 TypeScript CLI，试图把这件事改为生成流程：以 AGENTS.md 为入口，把跨项目的规则、项目约束、技术栈模块和可选技能分层保存，再为不同 Agent 生成或链接它们各自读取的文件。它不是又一种编码 Agent，也不负责替你编写规则；它解决的是“同一套规则如何被多个 Agent 一致加载”的工程问题。
本文用一个 TypeScript 服务为例，说明它的层级、最小接入步骤，以及哪些规则应当放在哪里。
先别把所有指令塞进一个文件
最直接的做法是维护一份超长 AGENTS.md，再把它复制到每个工具约定的位置。这在一个仓库、一个 Agent 时可以工作；但规则会自然分成几种生命周期：
- 所有仓库都要遵循的约束，例如不提交密钥、修改后必须测试；
- 某个仓库独有的目标、边界和架构术语；
- 与语言或框架相关的实践，例如 TypeScript 的错误处理、Python 的测试约定；
- 团队想复用、但并非每次会话都需要加载的技能说明。
seh 的文档把这些内容分为三层加一个可选包。L0 是 CLI 内置的基础内容；L1 位于 ~/.seh/，保存一台机器上的全局规则；L2 位于项目的 AGENTS.md 与 .seh/，保存应随仓库提交的项目索引和模块。若团队维护了 harness package（一个普通 Git 仓库），它可以携带全局规则、技术栈模板和 skills，并在解析时优先于本地默认层。
关键点不在目录名称，而在优先级：package → ~/.seh/ → CLI 内置核心。项目规则只扩展全局规则，而不应与它相互矛盾。这样，“禁止把生产凭据写入日志”可以只维护一次；“本仓库只支持 PostgreSQL，不引入 ORM”则留在项目层。
最小接入：先生成，再把源文件纳入审查
官方 README 给出的安装方式会下载自包含构建并将 seh 放入本地路径；它要求 Node.js 在 PATH 中。下面的命令把全局规则连接给 Claude 和 Codex，然后在当前 TypeScript 项目生成项目层。--yes 用于非交互执行，适合团队脚本或新机器初始化。
curl -fsSL https://raw.githubusercontent.com/manuuuel/seh/main/scripts/install.sh | sh seh init --global --agents claude,codex --yes cd api-service seh init --tech typescript --yes seh sync
初始化后的核心文件是项目内的 .seh/AGENTS.md、.seh/project.md、.seh/domain/architecture.md、.seh/domain/glossary.md、.seh/stack/typescript.md 与 seh.lock。其中 AGENTS.md 是一个轻量索引：它把真正的项目说明和按需加载的模块串起来；工具侧的 CLAUDE.md、GEMINI.md、AGENTS.md 或 Copilot 指令文件是从这个入口生成的链接，应当视作派生物，而不是人工编辑目标。
这一区分很重要。假如开发者直接改了 CLAUDE.md，下一次 seh sync 会按 .seh/ 的源内容重建它，手工修改就会消失。正确的评审对象应是 .seh/project.md、领域说明和技术栈模块；seh.lock 也应提交，以便其他机器按相同技术选择重建结果。
把“可执行边界”写到项目层
生成骨架后，最值得先填的不是泛泛的代码风格，而是 Agent 容易误判的边界。例如一个支付 API 可以在 .seh/project.md 中明确：写操作必须经过服务层；迁移需要人工确认；外部回调使用幂等键；本次任务不允许改变公开 API。领域文件再定义“订单”“结算状态”“补偿”等业务词，避免 Agent 把相近名词混用。
技术栈模块则适合写可复用的工程规则。以 TypeScript 为例，可以把运行时校验、错误返回、测试命令和禁止的依赖策略放进 .seh/stack/typescript.md。不要在规则里虚构项目命令；如果仓库的验证命令是 npm test，就写它；如果尚未确定，先留下待决定项，而不是让 Agent 假定 pnpm test 可用。
- 不在路由处理器中直接访问数据库；经由 service 层。 - 修改支付状态前必须保留幂等键检查。 - 不新增外部 SaaS 依赖，除非任务明确批准。 - 合并前运行项目已定义的测试与静态检查。
示例刻意没有给出不存在的 seh 配置字段：项目文件本身就是 Markdown，团队可以先用可评审的自然语言建立边界，再逐步把具体流程沉淀成模块。
用 sync 与 check 把“规则漂移”变成可检测状态
seh 的 sync 会根据 seh.lock 与 .seh/ 源文件重写项目索引和技术栈模块；README 将其描述为幂等操作：在源内容不变时重复运行不应产生变化。配套的 seh check 则在生成文件缺失或过期时以非零状态退出，适合接入 pre-commit 或 CI。
一个务实的接法是在提交前或 CI 中只检查派生内容是否和源一致，而不是让 CI 直接替开发者改文件：
seh sync seh check
这带来两个收益。第一，规则变更有明确 diff：评审者看到的是“为什么新增这条边界”，而不是七个 Agent 文件的重复改动。第二，团队可以把 Agent 支持范围扩大到 Claude、Codex、Pi、Gemini、OpenCode、Copilot 与 agents 互操作路径，而不用为每个工具维护独立正文。
还有一个常被忽略的收益是排障边界更清晰：当某个 Agent 的行为异常时，可以先确认它读取的派生文件是否由当前 .seh/ 源生成，再检查全局层、项目层和 package 的覆盖关系，而不是在多个手工副本里猜测哪次修改生效。对受监管或多人轮值的项目，这种“来源可定位”比单纯减少复制粘贴更有价值；规则本身仍需经过代码评审，但至少它的生效路径是可复现的。
不过 check 只验证生成物是否同步，不会判断规则本身正确、更不会验证 Agent 是否真的遵守规则。它应当补充而不是取代单元测试、代码审查、权限控制与 CI 质量门。
全局规则与项目规则如何取舍
全局层适合放“无论在哪个仓库都成立”的约束：不泄露机密、优先最小修改、先理解测试再改代码、报告不确定性。项目层适合放会随业务变化的事实：架构边界、命名约定、部署流程、数据保留、允许修改的目录。把后者塞到 ~/.seh/AGENTS.md 会让个人机器规则污染其他项目；反过来，把前者复制进每个仓库又会重新制造漂移。
harness package 则适用于团队希望把规则作为版本化资产共享的场景。它只是一个外部 Git 目录，不是 seh 代管的仓库：可包含 harness.json、全局规则、模板、项目覆盖内容和 skills。团队可以像管理内部脚手架一样用正常的 Git 流程评审它，再通过 seh package use 指向本地副本、用 seh package install 分发内容。
实际落地时，建议先把 package 限制为稳定的跨项目规范，而不要立刻搬运每个仓库的全部说明。比如统一的安全基线、提交信息约定和通用测试原则可以随 package 版本演进；支付、数据模型、发布窗口等业务事实仍应留在仓库内。升级 package 前，也应在一个代表性项目执行 seh sync 并检查 diff，确认新全局规则没有意外改变项目入口。这样既能共享维护成本，又能把变更影响限制在可评审范围内。
这也说明 seh 的边界：它不解决多 Agent 的任务调度，不代替权限隔离，也不会自动把模糊的团队文化变成可靠规范。它的价值在于降低“规则文件有多个副本”这一基础设施成本。若团队只有一种 Agent、规则极少且没有跨仓库需求，直接维护一个简洁的项目 AGENTS.md 往往更轻；当工具种类和仓库数量增长时，再引入可生成、可检查的层次会更划算。
结语：先统一源，再谈 Agent 一致性
AI 编码协作的稳定性并不只取决于提示词写得多漂亮，而取决于约束是否能被持续、可追溯地传递。se-harness 用 AGENTS.md 入口、项目模块、全局层和 sync/check 把这条链路显式化。先为一个真实仓库写清边界，提交源文件与锁定文件，再把 seh check 放到既有质量门里；这比一次性迁移所有 Agent 配置更容易验证，也更容易回滚。