Repo-Docs
为编码代理维护一套随代码演进的项目文档:导览、变更记录、代码地图与交接上下文,让仓库始终能自我解释。
- Star 数
- ★ 427
- 最近更新
- 4 个月前
- 主语言
- Python
- FA 评分
- 45/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code
- 费用
- 软件免费,模型调用费用自付
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 使用 Claude Code 或 Codex 进行氛围编码的开发者,希望代理每次改动后项目理解不随聊天记录丢失。
- 不适合
- 不支持技能安装的仓库需要手动改造,文档未说明做法
- 希望自动生成完整 API 文档或文件树导览的用户
- 官网
- yurunchen.github.io/repo-docs-skills ↗ 来自 GitHub 仓库设置
- 维护状态
- 近半年有提交最近提交 2026-07-12
- 源码审查
- 45/100 · 缺口较多
这个 Agent 能做什么,适合哪些场景?
Repo-Docs 是浙江大学 AI4GC Lab 开发的一个可安装技能包,用于解决“氛围编程”时代代码变动快于项目记忆的问题。它以 Claude/Codex 技能的形式安装到编码代理中,在每次真实的代理运行后,于仓库内生成并维护一组结构化文档,包括 repo-docs/README.md、单次真实运行的 walkthroughs/one-real-run.md、code-map.md、modules/、references/、glossary.md、change-log.md 以及面向后续代理的 AGENTS.md / CLAUDE.md。其核心是一套保守的同步循环:当用户提问或代理修改仓库时,只更新那个否则会误导下一位读者的最小页面。它还提供 repo-docs-zh 中文覆盖包,以及一个 Python 校验脚本 validate_repo_docs.py,用于检查源码定位符和文档漂移。该项目附带 install.sh / install.ps1 命令行安装脚本,文档质量标准明确(行为先于清单、证据可见、补丁外科式)。
Repo-Docs 以技能包形式安装(SKILL.md、REFERENCE.md、WRITING.md、PAGE_RULES.md、SCOPE_MODES.md、SYNC_RULES.md、QUALITY_RULES.md、EXAMPLES.md)。在仓库中运行时,它读取源码与运行证据,产出八个文档构件:入口 README、描述一次真实行为路径的 one-real-run 导览、将源码目录映射到职责/测试/易变点的 code-map、解释持久概念的 modules/、存放源码证据与质量审查的 references/、术语表 glossary.md、记录验证与同步锚点的 change-log.md,以及指示未来代理如何维护文档的 AGENTS.md / CLAUDE.md。它支持五种模式:Seed(新仓库记录目标与未知项)、Build(首次生成指南)、Sync(最小化修补将过时的页面)、Cleanup(删除生成的文档)、Question refinement(纠正错误的读者模型)。生成后可用 skills/repo-docs/scripts/validate_repo_docs.py 校验,支持 --lite、--seed 和 --repo-root 选项检查源码定位符与锚点漂移。
- 使用 Claude Code 或 Codex 进行氛围编码的开发者,希望代理每次改动后项目理解不随聊天记录丢失。
- 接手他人代理生成代码库的工程师,需要一条从入口到输出的真实行为导览而非文件树罗列。
- 团队维护者希望 README、源码、测试与代理记忆之间保持同步,避免文档漂移。
- 需要中英双语文档的项目负责人,可以使用 repo-docs-zh 中文覆盖包生成中文仓库指南。
- 想在文档中保留源码证据与质量审查记录的代码评审者。
- 希望向后续代理交接上下文、避免重复发现同一背景的多代理协作开发者。
安装与配置要点
摘自下方的安装和使用说明,以项目 README 的最新说明为准。
- 配置文件
~/.codex/skills~/.claude/skills~/.agents/skills- 安装说明涉及
- Windows · macOS · Linux
如何安装或部署这个 Agent?
方式一(推荐):在编码代理中给出自然语言安装请求:"Install the repo-docs skill from this project: https://github.com/YurunChen/repo-docs-skills. Make both repo-docs and repo-docs-zh available in my agent skill directory." 方式二(命令行):Linux/macOS 运行 curl -fsSL https://github.com/YurunChen/repo-docs-skills/raw/main/install.sh | bash;Windows PowerShell 运行 irm https://github.com/YurunChen/repo-docs-skills/raw/main/install.ps1 | iex;从源码检出运行 ./install.sh,可用 --agent all 安装到 ~/.codex/skills、~/.claude/skills、~/.agents/skills,或用 --target ~/.agents/skills 指定目录。运行时依赖:一个支持技能机制的编码代理(Claude Code / Codex)。
如何使用这个 Agent?
安装后用自然语言调用,例如:"Use the repo-docs skill to create docs for this repository." 或 "Use repo-docs-zh to create a Chinese repo guide for this project." 或 "Explain how this subsystem works using repo-docs and the current source." 生成的文档可用 python skills/repo-docs/scripts/validate_repo_docs.py /path/to/repo-docs --repo-root /path/to/repo 校验(小项目加 --lite,仅有计划的新仓库加 --seed)。
这个 Agent 有哪些优点和局限?
- 有明确的模式体系(Seed/Build/Sync/Cleanup/Question refinement),同步规则刻意保守,只修补会误导读者的最小页面,避免文档维护变成全面重写。
- 文档与源码证据绑定:references/ 存放源码证据,附带 validate_repo_docs.py 校验源码定位符和锚点漂移,可机器验证文档是否过时。
- 原生支持中文仓库指南(repo-docs-zh 覆盖包)与双语 README,适合中文团队。
- 产物面向后续代理(AGENTS.md / CLAUDE.md),在聊天结束后仍然有用,而非一次性文件树导览。
- 依赖具备技能机制的编码代理宿主(Claude Code、Codex 等);不支持技能安装的代理需要自行适配,仓库未提供其他集成路径。
- README 未说明许可证(License: unknown),企业采用前需向作者确认授权条款。
- 文档生成质量依赖代理自身的理解能力与运行证据;新仓库只能使用 Seed 模式记录计划与未知项,而非实现性说明。
- 校验脚本需要 Python 环境,命令行安装依赖能访问 GitHub raw 内容的网络环境。
这个 Agent 与同类方案有什么区别?
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Repo-Docs 当前 | 45 · 缺口较多 | Agent 插件 / 技能免费 + 模型费 | ★ 427 | 4 个月前 | Python | Codex · Claude Code |
| Keep the Why | 83 · 表现良好 | Agent 插件 / 技能免费 | ★ 240 | 3 天前 | JavaScript | Codex · Claude Code |
| VibeSkills — 智能技能编排器 | 64 · 存在缺口 | Agent 插件 / 技能免费 + 模型费 | ★ 3.8k | 12 天前 | Python | Codex · Claude Code |
| Softaworks Agent Skills | 44 · 缺口较多 | Agent 插件 / 技能免费 + 模型费 | ★ 2.7k | 8 个月前 | Python | Claude Code |
FollowAgents 如何评估这个 Agent?
查看各维度的扣分理由
材料展示了面向本地仓库生成和更新文档的流程,并明确要求以源码、测试和配置为依据;README 也说明安装方式。但所示内容未说明安装脚本具体访问或修改哪些路径、写入前如何征求确认、敏感内容如何处理、如何撤销变更或如何审查外部依赖,因此这些方面仅给部分分。归属信息仅在致谢中提及 AI4GC Lab,未提供可核验的发布者身份或安全维护渠道。
技能文件要求先读路由与专题规则、使用随附验证器,并在无法验证时说明原因;README 也列出验证命令。材料中 README 与技能入口对产物结构的描述基本相容,但给出的 SKILL.md 内容在中途截断,无法核对完整规则、错误处理或脚本依赖;因此只给部分分。
描述覆盖新仓库建档、首次构建、同步、清理、问答和中文文档等场景;技能还区分 Seed、Build、Sync、Cleanup 等模式,并要求普通问题先判断文档是否会误导。所示规则较清楚,但环境适配信息有限,未展示各代理环境、平台或权限差异的完整处理方式。
README、安装说明、产物表、模式表和源码布局提供了可读的导航;技能有明确文件职责和文档契约,名称也较一致。README 给出自然语言和命令行安装、使用示例及验证命令,但没有展示常见故障问答或完整已知限制。许可元数据明确未知,故许可项为 0;材料未给出版本发布与更新记录,也未明确维护责任和更新渠道,相关项仅部分得分。
产品面向具体的文档维护问题,规定 walkthrough、代码地图、证据页、术语表和变更日志等可直接使用的产物,并强调只修改会误导读者的最小页面。此结构显示出实际效用;但材料未提供运行后的结果或成本数据,无法证明文档维护负担与收益的平衡,因此成本效益仅部分得分。
技能明确要求证据优先、使用精确源码定位符,并对中文材料规定推断或未确认标签;验证器的职责也在文档中列出。README 与技能文件对核心产物和流程有一定相互印证,但没有提供完整实现、验证器源码或独立结果作为交叉证据;所示内容有截断,故不作更强判断。
- 材料中的 SKILL.md 内容在中途截断,不能据此确认完整指令、依赖、安装器行为或故障处理;未展示的文件应视为未知。
- 安装示例会通过 shell 执行远程脚本。审阅前应查看对应安装脚本并确认目标目录和覆盖行为;本评估未检查脚本内容。
- 许可元数据未知,使用或再分发前应核实许可。
常见问题
Repo-Docs 官网是什么?
Repo-Docs 免费吗?
Repo-Docs 开源吗?
Repo-Docs 安全吗?
Repo-Docs 还在维护吗?
Repo-Docs 是谁开发的?
谢谢反馈,我们会据此改进页面。