agents-md-starter 是做什么的？
输出：在仓库根目录下生成 AGENTS.md 作为单一事实来源，并生成一个包含 @AGENTS.md 的 CLAUDE.md（Claude Code 会读取 CLAUDE.md 并支持 @path 导入）。文件中的每个命令都必须已成功运行或明确标记为未验证。
步骤 1 — 扫描
python3 scripts/scan_repo.py /path/to/repo # 人类可读的摘要
python3 scripts/scan_repo.py /path/to/repo --json # 以 JSON 格式输出事实
python3 scripts/scan_repo.py /path/to/repo --draft > AGENTS.draft.md # 填充模板
它会检测：基于文件数量的编程语言、基于锁定文件的包管理器、package.json 中的脚本、Makefile 目标、pyproject.toml 中的工具（如 pytest、ruff、mypy、uv/poetry）、Go/Rust/Java 的构建文件、框架（如 Next.js、Astro、Vite、Django、FastAPI、Rails……）、单体仓库工作区、CI 工作流、环境变量示例文件以及现有的智能体规则文件。它绝不执行仓库代码。
步骤 2 — 在写入之前先阅读
- 阅读它找到的每一个现有规则文件（
CLAUDE.md、.cursorrules、.cursor/rules/*.mdc、.github/copilot-instructions.md、GEMINI.md、CONTRIBUTING.md）。保留其中真实的规则；合并、去重、删除通用规则（如“编写干净的代码”）。 - 阅读 CI 工作流：CI 运行的命令是“测试通过”的最可靠定义。
- 浏览 2-3 个有代表性的源文件，以捕捉实际的约定（如命名、错误处理、导入风格）——不要凭空发明代码中未遵循的约定。
步骤 3 — 验证命令
执行草案中的安装/构建/测试/检查命令（确保安全：不要执行部署、不要针对真实数据库执行迁移、不要发布）。对于每个命令：如果它能工作则保留；如果正确的变体显而易见则修复；否则标记为 (unverified) 并告知用户。如果测试套件速度较慢，则记录其耗时。
步骤 4 — 写入 AGENTS.md
从 assets/AGENTS.template.md 开始。优质内容的规则：
- 简短。 力求低于约 150 行。智能体在每次任务时都会读取此文件；每一行都消耗上下文。
- 具体且可检查：“提交前运行
pnpm test --filter web”比“测试你的代码”更好。 - 将命令放在前面。然后是布局、约定、注意事项以及“不要”规则。
- 记录不明显的内容：不应编辑的生成文件、测试所需的环境变量、需要在本地跳过的单个慢速测试、绝不能存放机密的地方。
- 对于单体仓库：在根目录的 AGENTS.md 中放置共享规则，在
packages/x/AGENTS.md中放置包特定的命令（支持此功能的智能体会读取最近的规则文件）。
步骤 5 — 与其他工具集成
- Claude Code：从
assets/CLAUDE.template.md创建CLAUDE.md（它包含@AGENTS.md）。如果CLAUDE.md已存在，则将其规则移至AGENTS.md，并在导入指令之后保留仅适用于 Claude 的备注。 - Codex：原生读取
AGENTS.md—— 无需其他操作。 - Cursor：读取根目录的
AGENTS.md；将.cursorrules的内容迁移到AGENTS.md中，并在用户同意后删除.cursorrules（已弃用）。仅将.cursor/rules/*.mdc保留给基于 glob 的规则。 - Gemini CLI：默认读取
GEMINI.md；在.gemini/settings.json中设置"context": {"fileName": ["AGENTS.md", "GEMINI.md"]}，或创建一个指向AGENTS.md的单行GEMINI.md。如果此键已更改，请查阅已安装版本的文档。 - 符号链接（
ln -s AGENTS.md CLAUDE.md）也可以工作，但在未启用core.symlinks的 Windows 系统上会出问题；导入方法更安全。
有关每个工具读取的文件，请参阅 references/tool-support.md。
步骤 6 — 报告
列出：创建/修改的文件、已验证的命令（含结果）、标记为未验证的命令、作为重复或通用规则被删除的规则，以及任何需要用户决定的事项（例如，是否删除 .cursorrules？）。除非用户要求，否则不要提交。