liyuhao957/relay-rules
GitHub: liyuhao957/relay-rules
一套为 Claude Code 和 Codex 设计的共享规则框架，通过从真实代码生成并维护经过验证的项目规则，让 AI agent 在跨会话工作时保持连续性并防止文档漂移。
Stars: 2 | Forks: 0
# Relay 规则
English | [简体中文](./README.zh-CN.md)
这是一套专为在你的代码库中工作的 AI agent（如 Claude Code / Codex）设计的规则：新会话会继续上一次的工作而不是从头开始，信任当前代码而非过时文档，并在停止前完成整个任务。
它是一个包含多个 Markdown 文件以及几个零依赖脚本和 hooks 的文件夹，你只需将它们复制到你的项目中即可。没有运行时，也没有框架。最常见的设置是一个 agent 跨越多个会话工作；Claude 和 Codex 交替工作也可以，而且空仓库同样适用。
## 安装
**1. 将此仓库克隆到你机器上的任意位置**
```
git clone https://github.com/liyuhao957/relay-rules.git
```
**2. 在你的项目中，用一句话告诉你的 agent**
无论是首次安装、项目中已经有了自己的规则文件，还是从旧版本升级——用的都是同一句话，你不需要弄懂任何参数标志：安装脚本会自动识别情况，并在输出中说明接下来该怎么做，然后 agent 会接手后续操作；任何被替换的文件都会先备份到 `.rules-kit/backups/`。安装完成后，它会读取你的真实代码，并用经过该项目验证的规则填充模板；任何它无法验证的内容（如实时配置、计费等）都会被标记为 `needs-user`，等待你确认——严禁猜测。
`。默认情况下，该脚本会拒绝覆盖已有的 `AGENTS.md` / `CLAUDE.md` / `.claude/`，并在错误信息中指明两种处理方式；agent 会根据实际存在的内容进行选择：
- 如果规则文件是你自己写的，不属于此工具包 → 使用 `--force` 重新安装：旧文件会被备份，然后被替换，并在适应过程中作为线索被读取。
- 如果之前已经安装过该工具包且这是一次升级 → 使用 `--upgrade`：仅更新工具包自身的组件——脚本、hooks、skills、工作流文档、`.agent/index.md` 索引以及示例配置，每个组件在替换前都会备份；你填写到规则文档中的项目事实将保持不变。请注意，索引和工作流文档属于工具包的一部分，会被新版本替换（你的旧副本在备份中——如果你修改过它们，可以将编辑合并回来）；如果最后的验证列出了缺失的新内容，agent 会从模板中将其合并一次。
**3. 重启 agent 会话并批准项目 hooks**
重启会使 agent 重新加载此设置；hooks（工具包安装的防护脚本）在获得批准前不会执行任何操作——Claude Code 会询问项目设置（如果没有出现提示，请检查 `/hooks`）；Codex 需要你信任项目的 `.codex/` 目录并通过 `/hooks` 审查 hooks。每次升级后也需要执行此操作。
这样就完成了。要确认它已安装并真正适应了项目：
```
/path/to/relay-rules/scripts/validate-installed-project.sh /path/to/project --require-adapted --require-candidates-reviewed
```
## 卸载
```
/path/to/relay-rules/scripts/uninstall-rules.sh --target /path/to/project # add --dry-run to preview
```
不会删除任何内容：已安装的文件会被移至备份，安装前你拥有的文件会恢复原位，携带你内容的备份文件会列出供你取回，剩下的 `.rules-kit/` 目录在你满意后可自行删除。如果项目是带有安装前提交记录的 git 仓库，git 回滚永远是最干净的卸载方式；如果脚本无法识别损坏的半安装状态，请手动删除文件映射中的路径。
## 日常运作方式
- **只有 `AGENTS.md`（约 35 行）保留在上下文中。** 所有其他规则文档均按需加载：触碰某个领域的文件，该领域的文档就会被载入，仅此而已。
- **当代码发生变化时，规则也会随之改变。** 在任何非微小的更改之后，agent 会运行两个扫描脚本：一个列出可能因 diff 而过时的文档，另一个将“此规则可能已过时”的候选项写入收件箱（`.agent/rule-candidates.md`），供 agent 验证、更新或拒绝。脚本只收集证据；真正的决策权仍在 agent 手中。
- **只有两件事会进行阻塞，且范围极窄。** 危险命令（强制推送、`rm -rf`、发布/部署）以及未处理的高风险收件箱项（机密、计费、发布、远程/生产环境状态）。其他一切都是建议性的。
- **任务中途停止会留下交接说明。** 包含目标、基线提交、已验证和未验证的内容——下一次会话会从这里继续。
## 详细信息
Deleting an account purges synced data within 24h.
user-journeys.md Sign up → verify email → create first project →
land on dashboard.
command-contract.md Test: npm test (ran it, passes)
Build: npm run build (ran it, succeeds)
drift-map.yml The "changed paths → docs to review" map,
tightened to this repo's real paths.
```
任何 agent 无法从代码、测试或工具中证明的内容（实时计费状态、生产环境配置、凭证）都不会被写入规则中——它们会被标记为 `needs-user` 等待你确认。
验证检查的是格式，而非正确性：字段是否已填充、模板占位符是否已消失、以及每个决策是否都有真实的原因。事实本身是否正确则取决于 agent 和你。
## 友情链接
- [linux.do](https://linux.do/)
针对已有的规则文件 / 升级，agent 实际上会做什么
Agent 会运行 `scripts/agent-install-rules.sh --target安装了哪些内容（文件映射）
``` AGENTS.md shared agreement; Codex reads it at startup, Claude via @import CLAUDE.md thin Claude entrypoint, imports @AGENTS.md .agent/ index.md the index: load only what the task needs adaptation-review.md Status: pending | adapted; plus needs-user items product-invariants.md durable product promises user-journeys.md main flows and the loops to close command-contract.md verified commands (+ generated candidates) quality-gates.md the loops that define "done" domains/*.md ui-copy, data-sync, build-test, release, localization, performance workflows/*.md adapt-rules, implement, review, continue, release drift-map.yml changed paths → docs to review; also drives on-demand loading rule-candidates.md the candidate inbox: scripts write, the agent decides rule-health.md when to prune, merge, or delete rules project-map.md etc. bootstrap-scan output (with bootstrap-report.md; clues only) handoff-template.md, work/ the handoff note template and where notes live decisions/ durable decisions worth leaving for whoever comes next doc-drift.md, *-policy.md mechanism and policy docs, read on demand .claude/ rules/*.md path pointers; auto-load on matching file reads skills/*/SKILL.md thin workflow entries (8; the Codex tree is generated from this side) agents/*.md reviewer / qa / docs-drift-checker subagents hooks/*.py + settings.json bash guard + Stop gate .agents/skills/* Codex skill tree — generated at install from .claude/skills .codex/ hooks/*.py + hooks.json bash guard + Stop gate + domain router scripts/*.py bootstrap-project-context, check-doc-drift, suggest-rule-updates ``` 建议提交的内容：`AGENTS.md`、`CLAUDE.md`、`.agent/`、`.agents/`、`.claude/`、`.codex/`、`scripts/`，包括处理完候选项后的 `.agent/rule-candidates.md`。请将 `.agent/work/*`（交接说明）保留在本地： ``` .agent/work/* !.agent/work/README.md ```适应过程会填充什么内容
安装后，`.agent/adaptation-review.md` 会显示 `Status: pending`。遵循 `.agent/workflows/adapt-rules.md`，agent 会读取你的真实代码，并将通用模板转换为已验证的事实： ``` Before (template) After (agent filled in, verified from real code) ───────────────── ─────────────────────────────────────────────── product-invariants.md Free tier is capped at 3 projects.收件箱如何防止被忽视
候选项是脚本为 agent 写下的待办便签：“这部分代码发生了变化，所以某些规则可能已经过时了。去检查一下，并做出决定。”Agent 会逐一处理，并从四种结果中选择一种：`promoted`（已验证，已写入规则）、`checked-unchanged`（已检查，无需更改）、`rejected`（不值得作为规则），或 `needs-user`（无法验证，留给你处理）。 - **每条规则一个候选项。** ID 是稳定的（`risk:billing`、`drift:ui-copy`）；在一个任务中触碰 6 个文件仍然只是一个候选项。已解决的候选项只有在出现真正的新证据时才会重新开启。 - 提交并不等于解决：未处理的高风险候选项在提交后依然存在。 - 如果在更改状态时没有写出真实的原因，则不算数；下一次扫描会将其还原。 - 已处理的项目会移动到文件底部的归档区。历史记录保持可读，且被拒绝的候选项不会再反复出现。 - 依赖项和构建输出（`node_modules/`、`dist/` 等）永远不会产生候选项，安装程序会自动解决其自身文件触发的问题。 - 只有**高风险**候选项（机密、计费、发布、远程/生产环境状态）会阻塞任务完成；日常工作不会触碰风险区域，因此你可以照常停止。 当规则本身开始变得嘈杂或过时，`.agent/rule-health.md` 提供了精简、合并或删除的指南。它的目的是保持小巧。什么会真正阻塞（以及什么不会）
| 机制 | 触发条件 | 是否阻塞？ | | --- | --- | --- | | Bash 防护 (PreToolUse, 两种工具) | 强制推送；`git reset --hard`；`git clean -fd`（删除未跟踪文件）；`rm -rf`（`node_modules`、`dist` 等可重建目录除外）；发布/部署/发布命令（release, deploy, publish, submit，包括 `npx vercel deploy`、`sh -c "npm publish"` 等包装形式）；通过常见基础设施 CLI（kubectl, terraform, supabase, firebase, psql, mysql）针对生产环境的变更；通过 `psql` 或 `mysql` 执行的破坏性 SQL | **是。** 退出码 2；通过 `RULES_HOOK_ALLOW_RISK=1` 绕过 | | 停止关卡 (两种工具) | 未处理的**高风险**候选项（`risk:*`：机密、计费、发布、远程/生产环境状态）；普通的偏移/命令候选项会被列出但绝不阻塞 | **是。** 列出待处理的高风险 ID 和重新检查命令；Stop 阻塞意味着“继续执行并修复此问题”，而不是“中止”；通过 `RULES_HOOK_ALLOW_PENDING=1` 绕过 | | 文档偏移报告 | 按需执行；在停止关卡阻塞时也会显示 | 否。提供需要审查的文档建议列表 | | 偏移映射自检 | 在适应过程之后，映射中以目录为锚点的 glob 无法匹配仓库中的任何文件（通常是目录被重命名） | 否。单行警告 | | Codex 领域路由器 | 首次触碰映射区域的编辑 | 否。单行指针 | | 其他所有操作 —— 质量循环、真实来源顺序、工作流 | 书面协议 | 否。根据设计，依靠 agent 的判断 | 停止关卡带有一个防循环开关（`stop_hook_active`），因此它永远不会永久阻塞。Bash 防护采用“默认失败”策略：如果它无法解析命令，它会直接阻止执行，而不是放行；防护内部的崩溃也会阻止执行，而不是静默传递命令。“不要信任过时文档”和“完成整个任务”之所以能够维持，是因为 agent 遵守了协议——规则使得正确的时机容易被捕捉，但它们并不证明正确性。Token 成本
固定成本包含两项：始终加载的 `AGENTS.md`（约 35 行），以及一次固定的任务结束检查（无论任务大小，消耗一两千个 token）。领域文档仅在其文件被触碰时加载；skills 仅在被调用时展开。 可靠的按需入口点是手动维护的 `.agent/index.md` 路由映射加上 `python3 scripts/check-doc-drift.py`，该脚本会机械地列出映射到你实际 diff 的文档。Claude 的 `.claude/rules/` 指针和 Codex 的编辑后路由器是额外的补充；`.claude/rules/` 基于文件作用域的自动加载在某些 Claude Code 版本中存在已知的上游 Bug（它要么加载所有内容，要么从不触发），因此不要将其作为唯一的依赖机制。 匹配在单词边界上是精确的：`ProductCard.tsx` 不会仅仅因为包含“prod”就触发生产环境规则。完整生命周期：安装 → 引导扫描 → 适应 → 验证 → 增长
1. **安装。** `agent-install-rules.sh` 复制模板，从标准的 Claude skill 树生成 Codex skill 树，在 `.agent/rules-kit.json` 中记录元数据，备份现有的规则文件，并运行引导扫描。此时项目已*安装*，但尚未*适应*。 2. **引导扫描。** `bootstrap-project-context.py` 扫描当前文件和配置，并写下线索，而非结论。一个名为 `sync.ts` 的文件是一个信号，而不是已验证的云端同步证据。 3. **适应** *(由 agent 驱动)*。遵循 `.agent/workflows/adapt-rules.md`，agent 检查当前的代码、配置、测试以及任何旧备份，仅将已验证的事实写入 `.agent/*`，将偏移映射的 glob 收紧到项目的真实路径，并将它们镜像同步到 `.claude/rules/*`。无法证明的高风险事实会被标记为 `needs-user`。 4. **验证。** `validate-installed-project.sh` 会检查结构是否存在、`CLAUDE.md` 是否导入了 `@AGENTS.md`、Codex skill 树是否与标准树匹配、脚本是否可执行，以及（在使用严格标志时）适应状态、占位符和候选项是否都已处理。检查的是格式，而非正确性。 5. **增长** *(由 agent 驱动)*。随着代码的更改，两个扫描脚本会显示出可能过时的文档和新的候选项，agent 会对其进行验证、确认无需更改、拒绝或标记为 `needs-user`。标签：AI编程助手, Claude, Codex, Cutter, CVE检测, 代码规范, 开发效率, 网络可观测性, 逆向工具, 防御加固