mcpField
F
forge-setup-project

forge-setup-project

github.com/mgratzerAgent 工作流8353 次安装3 天前更新
代码仓库

关于 forge-setup-project

forge-setup-project 是用于创建或更新项目上下文文件的 Agent 技能。它按层级整理指导内容，只保留无法从代码库中发现的信息。

主要功能

  1. 01审核现有项目指导文件
  2. 02创建或更新 AGENTS.md
  3. 03按主题组织按需文档
  4. 04移除冗余的 CLAUDE.md
  5. 05更新 .gitignore 和 README.md
  6. 06汇报就绪情况与后续步骤

适用场景

  1. 01为新项目设置上下文文件
  2. 02迁移旧版 CLAUDE.md 指导
  3. 03检查过时的 Agent 指令
  4. 04整理项目专属开发文档

安装

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

$npx skills add https://github.com/mgratzer/forge --skill forge-setup-project

安装后在 Claude Code 中输入/forge-setup-project确认已加载。

附带文件references/agents-md-template.mdreferences/output-format.md

详细介绍

设置或更新项目上下文基础设施

上下文分为三个层级：

层级文件作用
1 — 热记忆AGENTS.md始终加载。精简，集中记录约定。只包含 Agent 始终需要的信息。
2 — 温记忆docs/*.md按主题按需加载。只有内容值得其 Token 成本时才创建。
3 — 冷记忆规范、架构定义、运行手册复杂项目的按需参考资料。本技能不会创建此类文件。

核心原则：上下文必须值得其 Token 成本。 只包含 Agent 无法通过使用 Grep、Glob 和 Read 探索代码库来发现的知识。

AGENTS.md 是唯一的指导文件。不要创建 CLAUDE.md：如果不存在 CLAUDE.md 或 CLAUDE.local.md，Claude Code 会原生读取 AGENTS.md，因此创建符号链接或副本只会多出一个名称。只有当用户希望保留 Claude 专属内容时，才有理由使用 CLAUDE.md——此时文件内容应为 @AGENTS.md 后接该内容，绝不能是副本。

输入

可选的项目根目录路径（$ARGUMENTS；默认为当前工作目录）。可选：-- <additional context>，用于补充执行指导。

流程

第 1 步：评估现有内容

扫描项目根目录中的 AGENTS.md、CLAUDE.md、README.md 和 docs/。文件状态决定后续工作：什么都不存在 → 从头生成；只有旧版 CLAUDE.md，没有 AGENTS.md → 将其迁移为 AGENTS.md，然后更新；存在 AGENTS.md → 审查并更新。若 CLAUDE.md 是 AGENTS.md 的符号链接或副本，则在第 7 步中移除。

第 2 步：探索代码库

探索项目结构、工具链、CI/CD 和文档（全新项目可跳过）。将每项发现归类为可自行发现（Agent 可以自行找到）或需要文档说明（决策、约定、失败模式）——只有第二类内容应写入上下文文件。

评估Agent 就绪度：反馈循环（测试、代码检查工具、构建周期速度）、模块结构、应用程序的易读性、已知风险。成功时会打印数页内容的检查命令会让 Agent 的上下文充满噪声：在反馈循环部分，若工具有静默标志，则注明该标志；否则，为包装器留一个 ``，让它成功时打印一行，失败时打印全部内容。

第 3 步：审查现有指导

若指导文件已存在，则为每个部分评分：

标准检查项
具体性这是否描述了本项目，还是适用于任何项目？
不可发现性Agent 能否通过探索找到这些内容？如果能，这就是浪费上下文。
时效性这是否与当前代码库一致？核实命令、路径和模式。
信号密度可操作信息占总字数的比例是多少？
适用范围每项任务都需要这些内容，还是只有部分任务需要？针对单一区域（迁移、某个服务的日志）的指导应放入条件块，或放入它所指向的文档中。

按影响分组展示审查报告，并在应用更改前通过 AskUserQuestion 获得用户确认。

第 4 步：收集项目信息

使用 AskUserQuestion 询问代码无法揭示的内容：核心原则、反复出现的失败模式和领域不变量，以及探索过程中发现的任何模糊之处和第 3 步审查发现的缺漏。绝不要询问能从代码中发现的信息。决定询问内容时，纳入任何末尾补充的上下文。

第 5 步：生成或更新 AGENTS.md

创建或更新 AGENTS.md。控制在约 200 行以内——长度取决于通过不可发现性检查的内容，因此小型项目的文件应更短。结构请参阅 agents-md-template.md。迁移时，将获准保留的旧版内容整合进来，并在第 7 步中移除旧文件。

第 6 步：生成或更新 Tier 2 — docs/

创建 docs/architecture.md（设计决策、数据流、模块职责）和 docs/pr-workflow.md（分支命名、PR 检查清单、审查流程）；只有在探索过程中发现值得记录的内容时，才通过 AskUserQuestion 提出进一步编写文档（开发、编码指南、测试、特定领域）。

每份文档都必须通过不可发现性测试——空文档只会浪费上下文。

第 7 步：删除冗余的 CLAUDE.md 并更新 .gitignore

删除作为 AGENTS.md 符号链接、AGENTS.md 副本或现已迁移到其中的旧内容的 CLAUDE.md（若已纳入版本控制，则使用 git rm）。如果其中仍有 AGENTS.md 未包含的内容，删除前通过 AskUserQuestion 询问用户。如果其中包含用户希望保留的 Claude 专属内容，则将其精简为 @AGENTS.md 加上这些内容。如果存在 CLAUDE.local.md，请告知用户：只要该文件存在，Claude Code 就会跳过 AGENTS.md。删除 CLAUDE.md 时，请说明某些 Claude Code 版本和配置只读取 CLAUDE.md（具体情况）；解决方法是创建包含 @AGENTS.md 的 CLAUDE.md。向 .gitignore 追加缺少的、适用于技术栈的条目——绝不覆盖现有内容。

第 8 步：创建面向用户的文件

如果 README.md 不存在，则创建它（项目说明、快速入门、文档链接——供人阅读，而非作为 Agent 上下文）。如果已存在，则通过 AskUserQuestion 询问：替换、合并还是保留？

第 9 步：提交

暂存并提交新建或修改的文件：docs: set up agentic context infrastructure（更新时使用 docs: update context infrastructure）。如果存在无关的已暂存更改，或生成的文件仍有未解决的问题，则跳过提交。

第 10 步：总结

报告创建或更改的内容——参见 output-format.md。包含各 Tier 的状态和行数、Agent 就绪情况评估以及后续步骤。

指南

  • 不可发现性测试——“Agent 通过探索能找到这个内容吗？”如果能找到，就不要写。
  • 重信号，轻篇幅——优先用表格而非段落；省略空章节。
  • Tier 规范——AGENTS.md 保持在约 200 行以内。超过 200 行时，移至 Tier 2。
  • 边缘情况——对于 monorepo：建议为每个包单独添加 AGENTS.md。没有测试或 CI：将其列为后续步骤。

相关技能

下一步： 使用 forge-create-issue 规划第一项工作；如果想法仍较粗略，需要先通过聚焦提问逐步明确，则使用 forge-shape。

示例用法

/forge-setup-project
/forge-setup-project /path/to/project
/forge-setup-project -- keep the setup lean and call out missing feedback loops

评论

支持 Markdown