mcpField
R
repo-intent-documenter

repo-intent-documenter

github.com/jpcaparasAgent 工作流5669 次安装1 天前更新
代码仓库

关于 repo-intent-documenter

帮助 Agent 根据仓库中的文档、代码、测试和配置编写或更新 REPO_INTENT.md，明确项目目的、假设及待确认问题。其方法要求区分直接证据与推断，并为重要陈述标注依据和可信度。

主要功能

  1. 01盘点仓库文档与代码线索
  2. 02按模板编写或更新意图文档
  3. 03为陈述标注可信度等级
  4. 04为重要主张附上证据锚点
  5. 05保留未解决问题供确认

适用场景

  1. 01为仓库创建项目意图文档
  2. 02依据新证据更新现有意图文档
  3. 03在不写文件时于对话中说明项目意图

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jpcaparas/skills --skill repo-intent-documenter

安装后在 Claude Code 中输入/repo-intent-documenter确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

AGENTS.md
metadata.json
README.md
skill-card.prompt.md
agents/
.gitkeep
assets/
.gitkeep
evals/
evals.json
references/
document-contract.md
gotchas.md
methodology.md
scripts/
repo_intent_inventory.py
test_repo_intent_inventory.py
test_skill.py
validate.py
templates/
repo-intent.md

详细介绍

仓库意图文档编写器

编写一份有依据的仓库意图文档，让未来的 Agent 清楚了解项目的目的、假设和未解决的问题。

决策树

用户想要什么？

  • 创建或更新仓库意图文档 运行 scripts/repo_intent_inventory.py，检查代码库，然后编写或更新 REPO_INTENT.md。

  • 直接在对话中说明项目意图，不写入文件 使用相同的证据模型，在聊天中作答；只有在有帮助时才提供文档路径。

  • 基于现有意图文档继续处理 先阅读现有文档，保留已确认的陈述，仅修订与当前证据矛盾的说法。

  • 用户希望起草后打开文档 先编写文档，然后使用可用的本地机制打开。如果没有桌面打开程序，则报告绝对路径。

  • 仓库缺失或无法访问 请用户提供仓库路径或文件。不要仅凭项目名称臆造项目意图。

快速参考

需求操作
快速了解仓库结构python3 scripts/repo_intent_inventory.py <repo> --json
证据规则阅读 references/methodology.md
输出格式从 templates/repo-intent.md 开始，并阅读 references/document-contract.md
歧义处理初次检查后再提出有针对性的问题，而不是检查前提问
失败模式阅读 references/gotchas.md

默认工作流

  1. 确定仓库根目录。当前工作目录中若包含 .git、清单文件或现有项目文档，应优先使用该目录。
  2. 运行 python3 scripts/repo_intent_inventory.py <repo> --json，收集第一轮资料，包括文档、清单、测试、CI、入口点和 Agent 指令。
  3. 自行阅读信号最强的文件：根目录 README、AGENTS 或 CLAUDE 文件、包清单、CI 工作流、顶层源代码入口点、测试、示例和现有文档。
  4. 使用 templates/repo-intent.md 起草 REPO_INTENT.md。
  5. 将陈述标记为 Certain、Strong inference、Tentative 或 Open question。每项重要陈述都需要证据锚点。
  6. 仅询问将暂定陈述转为已确认意图所需的问题。
  7. 用户回答后，更新文档并在审查日志中记录确认内容。
  8. 如有要求，写入文档后打开文档供用户审阅。

证据标准

区分直接证据与解读：

  • Certain 表示源文件、README、清单、测试或配置中有直接陈述。
  • Strong inference 表示多个独立信号指向相同意图。
  • Tentative 表示该陈述虽然合理，但依据薄弱或仅有单一来源。
  • Open question 表示在用户回答前，Agent 不应将该陈述作为事实陈述。

尽可能使用文件锚点，例如 README.md、package.json、src/server.ts 或 tests/auth.test.ts。如果运行环境能以较低成本提供行号，也应注明。

输出路径策略

默认将 REPO_INTENT.md 放在仓库根目录，因为未来的 Agent 最容易发现根目录下的意图文件。只有当仓库明显将所有持久项目文档都放在 docs/ 下，且在根目录放置文档会违反本地惯例时，才使用 docs/repo-intent.md。

除非用户提出要求，否则不要自动编辑 AGENTS.md、CLAUDE.md 或其他持久 Agent 指令。若将意图文档链接到 Agent 指令中会有所帮助，应改为在意图文档中添加简短的“建议集成”说明。

提问流程

先完成初稿，再提问，让用户可以针对具体内容进行修正。

问题应当：

  • 与证据相关：说明造成歧义的文件或信号
  • 易于回答：优先采用简短选项或事实确认
  • 排定优先级：仅提出能显著改善未来 Agent 行为的最少问题
  • 不阻碍进度：如果用户尚未准备好回答，就将未解决的问题留在文档中

注意事项

  1. 不要把目录名称解读为产品策略。src/app 只能说明结构，不能证明客户意图。
  2. 不要掩盖不确定性。没有依据却语气笃定的句子，不如明确提出尚待解答的问题。
  3. 读取代码库之前，不要提出宽泛的探索性问题。这样做是为了让 Agent 先完成初步检查。
  4. 不要仅仅因为当前代码不完整，就覆盖已经确认的人类意图。
  5. 不要用冗长的架构清单掩盖实际用途。架构是为了支撑意图，而不是意图本身。

阅读指南

需求阅读
完整的检查方法、信号排序和置信度标签references/methodology.md
必需的文档章节、目标位置规则和审核流程references/document-contract.md
常见陷阱和恢复模式references/gotchas.md
Markdown 起始模板templates/repo-intent.md

评论

支持 Markdown