findscripter 何时使用
为项目编写面向 Agent的规范文档 AGENTS.md（及其同义副本 CLAUDE.md）时使用。这类文档是 Agent 读取的权威指令源，核心原则是最小化：Agent 有能力，不需要手把手教。目标 < 60 行，绝不超 100 行——文档越长，指令遵循质量越差。
该用：
- 用户要创建 / 更新 / 审计
AGENTS.md或CLAUDE.md。 - 需要从真实工具链与仓库布局中提炼出高信号、简洁的 Agent 指令。
- 现有 Agent 文档太长、重复、或已与项目实际约定脱节，要瘦身校正。
不该用（边界）：
- 写给人类看的教程式文档（README 的上手指南、贡献流程叙事）——读者不同，不该塞进 AGENTS.md。
- 把 linter / formatter 规则搬进文档（
.eslintrc、biome.json、ruff.toml已经是权威源，重复即漂移）。 - 罗列已安装的 skills / 插件（Agent 会自动发现）。
步骤 / 指令
A. 落地文件
1. 在项目根创建 AGENTS.md
2. 建符号链接让 CLAUDE.md 指向它（单一真相源，改一处即可）：
ln -s AGENTS.md CLAUDE.md
Windows 无符号链接权限时，退而求其次：保留一份副本并在更新时同步两边。
B. 写之前先勘察仓库（决定哪些内容值得入档）
3. 包管理器 —— 看 lock 文件判断：pnpm-lock.yaml / yarn.lock /
package-lock.json / uv.lock / poetry.lock
4. linter/formatter 配置 —— .eslintrc / biome.json / ruff.toml / .prettierrc
（识别它们的存在，但【不要】把其中规则抄进 AGENTS.md）
5. CI/构建命令 —— Makefile、package.json scripts、CI 配置里的权威命令
6. monorepo 信号 —— pnpm-workspace.yaml / nx.json / Cargo workspace /
子目录各自的 package.json
7. 既有约定 —— CONTRIBUTING.md、docs/、README 里已沉淀的模式（引用而非复制）
C. 按写作规则成文
- 标题 + 要点列表，不写段落散文
- 命令与模板用代码块
- 引用而非内嵌：「见 CONTRIBUTING.md」「按 src/api/routes/ 的模式」
- 无废话：不写开场白、结语、客套
- 信任 Agent 能力：省略显而易见的上下文
- 优先文件级命令：单文件 test/lint/typecheck 比全仓构建更快更省
- 不复制 linter：代码风格活在配置文件里，不在 AGENTS.md
必备小节（始终包含）：
## Package Manager —— 只写工具名 + 关键命令
Use **pnpm**: `pnpm install`, `pnpm dev`, `pnpm test`
## File-Scoped Commands —— 单文件命令比全仓构建快且省，有就必列
| Task | Command |
|------|---------|
| Typecheck | `pnpm tsc --noEmit path/to/file.ts` |
| Lint | `pnpm eslint path/to/file.ts` |
| Test | `pnpm jest path/to/file.test.ts` |
## Commit Attribution —— Agent 用自己的身份署名
AI commits MUST include:
Co-Authored-By: (the agent model's name and attribution byline)
例: Co-Authored-By: Claude Sonnet 4 <noreply@example.com>
## Key Conventions —— 项目特有、Agent 必须遵守的模式，保持简短
可选小节（确有需要才加）：API 路由模式（给模板不给解释）、CLI 命令（表格）、文件命名约定、项目结构提示（指出关键文件、标出要避开的遗留代码）、monorepo 覆盖（子目录的 AGENTS.md 覆盖根目录）。
示例
最小化 AGENTS.md 骨架：
# Agent Instructions
## Package Manager
Use **pnpm**: `pnpm install`, `pnpm dev`
## Commit Attribution
AI commits MUST include:
Co-Authored-By: (the agent model's name and attribution byline)
## File-Scoped Commands
| Task | Command |
|------|---------|
| Typecheck | `pnpm tsc --noEmit path/to/file.ts` |
| Lint | `pnpm eslint path/to/file.ts` |
| Test | `pnpm jest path/to/file.test.ts` |
## API Routes
[模板代码块，不写解释]
## CLI
| Command | Description |
|---------|-------------|
| `pnpm cli sync` | Sync data |
注意事项
- 长度即质量：盯住 < 60 行、绝不超 100 行。审计旧文档时，删比加更重要。
- 反模式清单（看到就删）：
- 「Welcome to...」「This document explains...」之类开场白。
- 「You should...」「Remember to...」之类说教。
- 已在配置文件里的 linter/formatter 规则。
- 罗列已装 skills/插件（Agent 自动发现）。
- 有文件级命令时还写全仓构建命令。
- 显而易见的指令（「run tests」「write clean code」）。
- 解释「为什么」（只说做什么）。
- 大段散文。
- 引用 > 内嵌：能指向现有文档就别复制，复制即制造未来的漂移源。
- monorepo：子目录的
AGENTS.md覆盖根目录同名文件；按需在子包放局部覆盖，根文件保持通用。 - 本条非环境特定校验的替代品；输入、权限、安全边界或成功判据缺失时，先停下问清再写。
互见
- related：
skill-creator—— 同属「为 Agent 沉淀可发现文档」家族；写 SKILL.md 与写 AGENTS.md 共享「最小化、高信号、信任模型能力」的同一套心法。 - related：
agent-tool-design—— 工具描述与 AGENTS.md 都是被载入上下文、共同引导 Agent 行为的「契约文本」，精简与无歧义原则相通。 - combines_with：
skill-optimizer—— 写完 AGENTS.md 后，可借其评测/迭代思路验证指令是否真的改变了 Agent 行为，而非自我感觉良好。
采编自 sickn33/antigravity-awesome-skills（MIT）。