repo-fit：AI Agent 工具实践指南

真正理解repo-fit，要从它处理的任务开始：任何存储库的小型基础：规则、看板、会议简介和安全自动保存，它首先查看您拥有的内容，然后进行调整。实际做安全分析时，经常会碰到授权边界、证据完整性和误报需要同时控制，所以功能列表并不能代替验证。我的评估方法是在明确授权的样例或离线靶场中验证，然后检查输入边界、证据链、误报率和安全中止机制是否与文档一致。编辑判断上，具备授权环境和复核能力的安全人员可以优先研究它；其他团队不必为了热门标签勉强接入。

回购拟合

适合任何工作存储库。 将其指向一个存储库，无论是全新的还是十年前的。它会找到缺少的内容，仅添加该内容，然后为您留下一个看板、一个会话摘要和 Claude Code 和 Codex 都遵循的安全自动保存。如果没有预演和你的同意，什么都写不出来。它写入的所有内容都可以撤消。

git clone https://github.com/JimmySadek/repo-fit.git && node repo-fit/bin/repo-fit.mjs audit /path/to/your/repo

第一个命令是只读的：它打印报告并且不进行任何更改。

30 秒后查看

1.审计一个没有结构的存储库。 实际输出，修剪：

Verdict
**3 of 16** foundation checks are in place, **3** partly, **10** missing.
Biggest gaps: No secrets in Git: .env exists and is not ignored; Off-machine backup: no remote ...

| F8  | Tracked work (tasks, jobs, questions) | ❌ | no board or task tool            | Add a board |
| F17 | No secrets in Git                     | ❌ | .env exists and is not ignored   | Untrack, add to .gitignore and rotate the secret |
| F18 | Off-machine backup (a remote)         | ❌ | no remote: commits exist only on this machine | Add a private remote (needs your approval) |
| F19 | Work happens off main                 | ⚠ | on main, 2 uncommitted           | Work on a branch; autosave uses wip/ |

2.仅应用您批准的步骤。 每次应用首先都是一次试运行，显示每个文件和差异。 --apply 写有备份和收据； undo 将其反转。

# Dry run: acme-notes
Nothing is written yet. Review, then run again with --apply.
- **A-02** ➕ create `docs/00-home/board.md` (13 lines)
- **A-06** ➕ create `docs/00-home/open-questions.md` (7 lines)
- **A-10** ➕ create `scripts/playbook/brief.mjs` ... and the hook file for your tool

3.每个会话都以简短的开始，在助理说一句话之前用钩子打印：

 acme-notes · main · 7 uncommitted · last commit 2026-10-02
⚠ On main: the playbook rule is never to commit here. Work on a branch.
 Active (1): B-001 Fill in the README, people page and current view → Write the one-sentence purpose
➡ Suggested start: B-001
 Review queue: 4 nobody links to (notes/launch-plan.md · notes/meetings/2026-09-12-acme-call.md · +2 more)

这是给谁的

• 在 Git 中记录笔记、研究和决策的构建者和创始人，并希望 AI 助手能够从上次停下的地方继续，不遗漏任何内容。
• 任何拥有无结构增长的现有存储库的人。它映射您已有的内容，不移动任何内容，并一次按批准的步骤添加缺失的部分。
• 在 Claude Code 和 Codex 之间切换的人并希望这两种工具都能阅读一本规则手册。

不适合：第二个大脑。没有语义搜索，没有维基百科，没有数据库。请参阅下面的“范围”。

状态：公开测试版。 由一人在 macOS 上构建和测试；自动化测试在 macOS、Linux 和 Windows 上运行。仅通过 Claude Code 进行现场验证。 Codex 和 GitLab 未经测试。在依赖它之前，请阅读最后的“状态”部分。

它有两半：

得到它

您需要 Node.js 18 或更高版本以及 Git。无需安装任何内容：没有依赖项，没有构建步骤。

git clone https://github.com/JimmySadek/repo-fit.git
cd repo-fit
node bin/repo-fit.mjs help

首先使用两个只读命令：detect <repo>（机器和存储库拥有的内容）和audit <repo>（上面的报告）。

使用 AI 代理： 打开您想要在 Claude Code 或 Codex 中设置的存储库，并说：“在 <path to your clone> 的 repo-fit 文件夹中读取 INSTALL.md 并在此存储库中设置剧本。在编写任何内容之前，请先给我演示一下。”

作为一项技能（可选，未经维护者机器之外的测试）： 将 skill/repo-fit 复制到工具的技能文件夹（Claude Code 为 ~/.claude/skills/repo-fit，Codex 为 ~/.codex/skills/repo-fit），或将其添加到工具之间同步技能的任何内容中。然后告诉技能你的克隆在哪里，一次：

node bin/repo-fit.mjs prefs set home /path/to/your/repo-fit

git pull 后，再次复制技能，以便安装的副本保持最新状态。

提示： node bin/repo-fit.mjs prefs set owner "Your Name" 将新仓库名称设置为所有者。如果没有它，repo-fit 将使用 --owner，然后是存储库的 git user.name，然后是“所有者”一词。

回购协议得到什么

<repo>/
├─ README.md · AGENTS.md (managed core block) · LEARNINGS.md · playbook.json
├─ CLAUDE.md                  only if Claude Code is a chosen tool: 3 lines, imports AGENTS.md
├─ .claude/settings.json      Claude Code hooks: session brief, autosave, capture check
├─ .codex/hooks.json          Codex hooks (untested, needs /hooks trust)
├─ scripts/playbook/          brief · check · autosave · lib (vendored, version-stamped)
├─ docs/00-home/              current · board · log · open-questions · people
├─ docs/decisions.md · docs/sources/founder-input/ · docs/research/ · docs/templates/
└─ outputs/                   one folder per output, each with a README

命令

node bin/repo-fit.mjs detect <repo>                  # read-only: machine, repo, existing tools, what it would ask
node bin/repo-fit.mjs detect <repo> --json           # the same, for scripts
node bin/repo-fit.mjs audit <repo>                   # read-only report and plan for an existing repo (prints Markdown)
node bin/repo-fit.mjs audit <repo> --area docs/brand # only that area for notes, links and old documents
node bin/repo-fit.mjs audit <repo> --out report.md   # also --json; you choose where the file goes
node bin/repo-fit.mjs apply <repo> --steps A-01,A-10 --tool claude --hooks brief --autosave off   # dry run: shows every file and diff
node bin/repo-fit.mjs apply <repo> --steps A-01,A-10 ... --apply                                 # writes, backs up, writes a receipt
node bin/repo-fit.mjs apply <repo> --steps A-01 --word-cap 1500 ...                             # a cap for the current view, if the repo has none written down
node bin/repo-fit.mjs skip <repo> D-01 --reason "our rules cover it"                      # dry run; --apply records it in playbook.json
node bin/repo-fit.mjs undo <repo>                    # dry run; add --apply to put back what the last apply changed
node bin/repo-fit.mjs undo <repo> --force --apply    # also takes back files you changed since; your version is kept in .playbook/undone/
node bin/repo-fit.mjs connect <repo> --host github   # no remote yet: dry run; --apply creates an EMPTY PRIVATE remote. Never pushes
node bin/repo-fit.mjs tools <repo>                   # tool versions vs the limits in guidance/gates.json; --update claude [--apply]
node bin/repo-fit.mjs prefs                          # your standing choices, kept outside repos
node bin/repo-fit.mjs prefs set owner "Your Name"     # who new repos name as owner (else --owner, else git user.name, else "Owner")
node bin/repo-fit.mjs guidance check                 # which guidance is due for a refresh
node bin/repo-fit.mjs help                           # every command
node bin/repo-fit.mjs init <repo> --dry-run --name "Name" --owner "Owner" --tool both --models claude-opus-5-5
node bin/repo-fit.mjs status <repo>                  # is the repo behind the playbook?
node bin/repo-fit.mjs update <repo>                  # dry run: prints the diff
node bin/repo-fit.mjs update <repo> --apply          # writes it, commits nothing

init 永远不会覆盖文件，因此它在现有存储库上是安全的。 update 仅管理存储库采用的内容：核心块（当 AGENTS.md 拥有它时）、供应脚本（当 scripts/playbook/ 存在时）和 playbook.json 中的版本标记。它从不添加任何部分； status 将缺失的部分列为“未采用”或“故意跳过”(repo-fit skip)，而不是“落后”。核心块是用存储库自己的路径编写的（请参见下面的 paths），因此它永远不会命名存储库没有的文件。

由代理设置： 给它 INSTALL.md （它命名步骤、批准和撤消）。任何写入命令都接受 --pin <version>。

该设置旨在通过 回购拟合技能 运行，该技能询问回购适用于哪些工具和模型，读取匹配指南，应用该套件并验证它。

四个脚本

适应已经有自己系统的repo

在现有的存储库上，audit 首先评估，然后对发现的内容进行排序：

• 保持原样： 存储库已经以自己的方式涵盖了哪些内容。它自己的检查脚本和挂钩、脚本中的单词上限或记录器列表、决策生命周期（decisions/proposed、accepted）、如何保存原始输入、书面大文件策略以及在当前视图而不是面板中跟踪的工作（，算作到位）。
• 与核心块冲突：其中完整块与存储库的规则（检查、提交、决策、原始输入、状态、字数上限）相矛盾。 apply --steps D-01 编写了一个细长块，它遵循每个主题的存储库规则，因此存储库保留一个完成的定义。
• 受保护的路径：规则称为仅追加或只读的文件夹、playbook.json 中的 protectedPaths 以及交付的输出。里面的发现仅被列出，不提供修复、移动或存档。
• 值得改进：计划。当存储库运行自己的挂钩或检查时，A-10 就成为决定。 A-01 复制存储库自己的字数上限和记录器列表。

repo-fit skip <repo> <ID> --reason "..." 记录了您故意遗漏的步骤，因此 audit、status 和 update 停止提供它。检测是对规则文件和脚本进行模式匹配，因此每个发现都会引用它来自的行：在依赖它之前检查它。

连接点：审核队列

采用维护者自己的知识库，它是防止笔记过时的部分。没有数据库，没有搜索索引，没有供应商。

• 吸收规则（在核心块中）：从主题的中心开始，搜索每个拼写，合并到现有的注释中，保留与日期的冲突，然后连接（中心、当前视图、问题、决策）。
• 中心是文件夹 README，其中列出了旁边的每个注释（check 强制列出）。已有 hubs 文件夹的存储库将其映射到 paths.hubs 下。
• 审阅队列，在每个会话摘要和 check 中作为警告：注释没有任何链接，注释未触及 staleNoteDays（默认 180），没有计划审阅，并注释其 review_after: YYYY-MM-DD 日期已过。档案、输出、模板和文件夹 READMEs 被省略。 reviewIgnore 需要额外的 glob。 Wiki 风格的 [[links]] 计数。
• 未按设计构建： AI 检查器读取新输入的含义并询问它是否重复或与注释相矛盾。维护者的存储库与付费供应商一起执行此操作。在这里，助手在吸收的同时做出判断，因此会话中不会丢失任何内容；缺少的是会议之外自动的第二意见。稍后它将作为可选的附加组件安装。

2 级自动保存：规则

• 切勿在 main 或 master 上提交。在受保护的分支上，它切换到 wip/<date>-<tool>。
• 仅提交允许列出的路径（playbook.json、默认 docs/**、输出 READMEs、LEARNINGS.md）。跳过超过 5 MB 的看似秘密的名称和文件。
• 使用 --only 进行提交，因此您上演的任何其他内容都会保持上演状态。
• 添加命名该工具的 Host: 预告片。
• 从不推。
• 由于同样的原因，Stop 挂钩每个会话最多阻塞一次。它不依赖于stop_hook_active。尽管可以看到 2.1.284 正在发送它，但 Claude Code 的文档并未列出它。

安全和隐私

• 没有--apply就什么都不会被写入。每个写入命令首先都是一次试运行，备份其编辑的内容，写入收据并且可以撤消。
• 它永远不会推送，永远不会安装工具，永远不会为您登录。 connect 可以创建一个空的私有远程，只有在您批准确切的命令后。
• 它的内容： 您指向的存储库（文件名和大小、规则文件、从 URL 中剥离的任何密码或令牌的 Git 远程、类似秘密的文件名称，但绝不是其内容）； gh 和 glab 登录了哪些账户（绝不是令牌）；对于 tools，最新 Claude 代码会话日志中 ~/.claude/projects 下的版本号。
• 要了解的一个副作用： 要查看安装的内容，detect 在它查找的工具（git、gh、glab、node、python3、jq、claude、codex、gemini 等）上运行 --version，在 gh 上运行 auth status 和glab。 repo-fit 本身不写入任何内容，但其中一些工具在运行时会在您的主文件夹中创建自己的配置或临时文件。测试中看到 glab 和 gemini 做到了这一点。
• 网络： 当使用 npm 安装 Claude Code 时，tools 会向 npm 询问最新的 Claude Code 版本（--offline 会跳过它）。 connect 仅通过 gh 或 glab 与您的 Git 主机对话；它的试运行会执行一项只读名称检查。 claude update 仅与 --update claude --apply 一起运行。没有其他的事了。
• 您的常设选择 (repo-fit prefs) 位于 ~/.config/repo-fit/preferences.json 中，位于每个存储库之外。

测试

node --test

84 个自动化测试，无依赖性。它们在一次性沙箱（一个假的主文件夹，因此不依赖于您的机器）中运行，并涵盖：新的和现有的存储库上的每个命令、不写入任何内容的空运行、撤消、安全规则（从不覆盖、远程 URL 中的令牌从未打印）、会话摘要、自动保存、停止和 PreCompact 挂钩以及陈旧指导警告。过去的每个错误都有一个测试失败而没有修复。

GitHub 操作工作流程 (.github/workflows/test.yml) 在 macOS、Linux 和 Windows 上运行，节点 18、20 和 22。首次运行，2026 年 9 月 30 日：macOS 和 Linux green 在所有三个节点版本上。 Windows 未能通过 43 个中的 2 个，原因之一是 Windows 行以指导日期结尾。这是固定的，但 Windows 作业仍然允许失败，直到运行确认为止。

范围，一行

任何存储库、技术或注释的平衡基础。 没有第二个大脑：没有语义搜索，没有维基，没有记忆数据库。它应该查看存储库和机器已有的内容，进行调整，并在使用任何内容之前询问。

状态（测试版，0.5.0）

构建并测试（每个写入命令都是先试运行，编辑前备份，写入收据，并且可以撤消）：

经过现场验证：真正的 Claude Code 会话（工作室存储库）中的会话简短挂钩、薄 CLAUDE.md 导入（机器人存储库）、真正的私有 GitHub 远程（在真实项目上，然后在 repo-fit 本身上），以及真正的 Claude Code 2.1.284 桌面会话中的 Stop-hook 自动保存（一次性） repo：它关闭了 wip/<date>-claude-code 的受保护分支，使用 Host: 预告片提交了一个文件，没有推送任何内容），Stop block 及其每会话一次的防护，以及 PreCompact 自动保存（它提交了一个在会话外编辑的文件，就在压缩之前）。

尚未建成：

• 板适配器（Backlog.md、GitHub 或 GitLab 问题）。故意推迟：经审计的回购协议均未使用。
• 工作工作室配置文件（创意工作室存储库）和交付配置文件（客户交付存储库）。今天的工具包是知识库简介。通过 paths 映射（审核，然后应用）采用不同组织的存储库（作业文件夹、编号规范、它们自己的脚本），从而重用它们已有的文件。
• 共享套件：散列源存档、身份门、实体寄存器、CI。 （工作套件的覆盖范围检查和审查队列已构建；请参阅“连接点”。）
• 制导源的自动漂移检测。今天：日期、每周仅更新报告和手动例程。

尚未证实：

• 出现 Stop 块的原因只有一个：自动保存列表之外的未提交文件。另外两个（自动保存失败，今天没有日志行）未实时触发。
• 终端 claude (2.1.270)：其登录已过期，因此没有任何运行。仅 2.1.284（桌面应用程序）经过验证。
• 一切 Codex 特定的内容（钩子、信任审查）。仅根据文档起草。
• connect 具有真实的 GitLab 主机。只有 gh 路径真正运行。
• 视窗。测试在 macOS 和 CI 中的 Linux（节点 18、20、22）上通过。在 Windows 上，43 个中的 41 个在行结束修复之前通过；修复后的运行尚未开始。