Repo-Docs
为编码代理维护一套随代码演进的项目文档：导览、变更记录、代码地图与交接上下文，让仓库始终能自我解释。
- Star 数
- ★ 468
- 最近更新
- 2 个月前
- 主语言
- Python
- FA 评分
- 证据不足
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 使用 Claude Code 或 Codex 进行氛围编码的开发者，希望代理每次改动后项目理解不随聊天记录丢失。
- 不适合
- 不支持技能安装的仓库需要手动改造，文档未说明做法
- 希望自动生成完整 API 文档或文件树导览的用户
- 源码审查
- 证据不足
这个 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 中文覆盖包生成中文仓库指南。
- 想在文档中保留源码证据与质量审查记录的代码评审者。
- 希望向后续代理交接上下文、避免重复发现同一背景的多代理协作开发者。
如何安装或部署这个 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 当前 | 证据不足 | Agent 插件 / 技能免费 + 模型费 | ★ 468 | 2 个月前 | Python | Codex · Claude Code |
| VibeSkills — 智能技能编排器 | 46 · 缺口较多 | Agent 插件 / 技能免费 + 模型费 | ★ 3.5k | 26 天前 | Python | Codex · Claude Code |
| Softaworks Agent Skills | 51 · 缺口较多 | Agent 插件 / 技能免费 + 模型费 | ★ 2.5k | 6 个月前 | Python | Claude Code |
| Vibe Coding 中文实战指南 | 38 · 缺口较多 | 命令行工具免费 | ★ 16k | 今天 | Python | Codex · Claude Code |
FollowAgents 如何评估这个 Agent？
- 仓库未声明许可证，企业内使用前必须先确认授权条款。
- curl|bash 远程安装方式存在供应链风险，建议先审查 install.sh 内容再执行。
- SKILL.md、验证脚本与安装脚本源码未纳入本次审查证据，实际权限与写文件行为未经核实，建议在沙箱中先行试用。
- README 引用的 2026 年 arXiv 统计数据仅为背景论据，不代表本工具效果已被验证。