AGENTS.md — 模板完整模式将{{PLACEHOLDER}}标记替换为检测到的项目值。删除条件不满足的部分。此模板生成丰富的AGENTS.md。若要生成最小化版本agents.md 标准请使用agents-minimal.md。对于 monorepo 嵌套文件请使用agents-nested.md。# AGENTS.md Compatible with the [agents.md](https://agents.md) standard (60k projects). Specific rules in .agents/rules/ — {{RULE_CATEGORIES_LIST}}. ## Project Overview {{PROJECT_OVERVIEW}} {{DOC_IMPORTS}} {{WHO_USES_THIS}} ## Setup commands {{SETUP_COMMANDS_BULLETS}} {{READ_THIS_FIRST}} ## Source Files {{SOURCE_FILE_LIST}} ## Where to edit {{WHERE_TO_EDIT}} ## Essential Commands | Command | Purpose | When | | ------- | ------- | ---- | {{ESSENTIAL_COMMANDS}} {{ENVIRONMENT_VARIABLES}} ## Verification Cycle {{VERIFICATION_CYCLE_INTRO}}{{VERIFICATION_CYCLE}}{{E2E_MATRIX}} {{MONOREPO_REBUILD_NOTE}} ## Before committing {{BEFORE_COMMIT_CHECKLIST}} ## Pre-validate {{PRE_VALIDATE}} ## Code Style {{CODE_STYLE}} {{IO_CONTRACT}} ## Hard Rules {{HARD_RULES}} ## Prohibitions {{PROHIBITIONS}} ## Boundaries {{BOUNDARIES}} {{GENERATED_ARTIFACTS_POLICY}} {{SUBSYSTEM_RULES}} ## Global Conventions {{GLOBAL_CONVENTIONS}} {{ARCHITECTURE_DECISIONS}} {{DOC_UPDATE_CHECKLIST}} {{INTENT_ROUTING_TABLE}} {{ERROR_TAXONOMY}} {{WRITING_STYLE_GUIDE}} {{GOTCHAS}} {{SSH_TROUBLESHOOTING}} ## Definition of Done {{DEFINITION_OF_DONE}} {{TASK_GUIDES}} {{CONTRIBUTION_GUARDRAILS}} {{VERSIONING_POLICY}} {{RELEASING_SECTION}} ## PR instructions {{PR_INSTRUCTIONS}} {{AGENT_DISCLOSURE}} {{RULE_FILE_LINKS}} {{CODEGRAPH_SECTION}}始终包含的部分{{PROJECT_OVERVIEW}}一句话。Package.json 的description或推断的内容。{{SETUP_COMMANDS_BULLETS}}3-5个要点安装、开发、构建、测试、剥除。格式- ‘’。{{SOURCE_FILE_LIST}}扁平的树每个文件只有一行用途。然后是一个功能到文件的表格## Feature map | Feature | Files | |---------|-------| | CLI entry | src/cli.ts | | Core logic | src/add.ts |5-8 行将常见操作映射到具体文件。这对代理比单独的目录树更有用。{{WHERE_TO_EDIT}}与特征图相同但表述为“为了X需要编辑什么”任务 → 文件。如果源文件已经包含两者这可以更轻量。{{ESSENTIAL_COMMANDS}}有三列的表格命令 | 目的 |何时。添加一个“何时运行”决策列| pnpm test | Run all tests | Fast iteration | | pnpm test:run | Single-run tests | Before committing | | pnpm typecheck | TypeScript check | Before committing |{{VERIFICATION_CYCLE_INTRO}}每次代码更改后。在未通过以下检查前不要将任务标记为完成或者如果存在端到端矩阵首先运行最小的相关验证。{{提交前检查清单}}3-4 项验证周期、格式检查、锁文件验证。{{CODE_STYLE}}2-4 个项目特定的规则。不要提供通用建议。{{PRE_VALIDATE}}运行与 pre-commit 钩子完全相同的命令以避免缓慢的 CI lint-staged 失败。格式- Run {{PRE_COMMIT_CMD}} on changed files before committing — this is what CI runs.检测自.githooks/pre-commit、lint-staged配置、.husky/pre-commit。阅读实际的钩子以获取确切命令。{{HARD_RULES}}2-3 条编号的、不可协商的规则。违反 拒绝。检测来源.env.example → secrets 规则tests/ → 测试规则monorepo → 合同同步规则。{{禁止事项}}2-3 个“绝不做 X”的要点。将“绝不”加粗。从项目背景中检测通用“绝不创建 README 或 markdown 文档除非明确要求。”如果 TypeScript 启用严格模式“绝不使用any类型或as any断言。”如果存在发布脚本“绝对不要在功能拉取请求中提升版本号。”如果生成的构建输出存在“绝不手动编辑生成的文件。”如果是单体仓库“绝对不要直接推送到上游的 main 分支。”{{BOUNDARIES}}两个子部分“先问”和“绝不”。从项目中检测如果是 monorepo → 跨包重构规则。如果是 ORM → 破坏性数据规则。如果是构建输出 → 生成文件规则。Secrets 和破坏性 git 是通用的。{{AGENT_DISCLOSURE}}如果存在 CONTRIBUTING.md 或 PR 模板请添加代理归属规则。格式- All agent-drafted GitHub content (PR comments, reviews, issues) must include attribution footer. - Never mention or tag individuals unless explicitly authorized. - Drafted-by: footer required on all agent-generated GitHub messages.{{GLOBAL_CONVENTIONS}}5-8 个要点包管理器、导入规范、命名、语言、验证方法。{{完成的定义}}4-6 个编号的清单项。包括类型检查/代码风格检查/测试、新增测试、文档更新、无警告。{{PR_INSTRUCTIONS}}2-3 个要点。如果项目有 PR 模板请包含“目标每个 PR 选择一个”范围模式- Pick ONE goal per PR. Frame the title to reflect it. - Conventional commits: feat:, fix:, refactor:, test:, chore:. - No AI attribution in commits.条件部分检测并包含{{WHO_USES_THIS}}由 AI 代理使用的 CLI 工具、API 或 SDK## Who uses this This CLIs primary consumers include AI agents (Claude Code, Cursor). Error messages, output format, and flag design directly affect agent success rates. Every error message will be parsed by an AI to decide its next action.{{首先阅读此内容}}如果docs/或doc/有 3 个 markdown 文件。在进行更改之前要阅读的文件顺序列表。{{ENVIRONMENT_VARIABLES}}如果发现仅占位符的.env.example条目或源引用例如process.env.NAME请生成一个包含 3-8 个变量的表格列为 Variable | Required | Purpose。切勿打开.env、.env.local或其他包含秘密的环境文件并且切勿将值复制到生成的指令或记录中。{{E2E_MATRIX}}如果项目同时有单元测试和端到端测试| Change | Unit tests | E2E tests | |--------|:----------:|:---------:| | New feature | Required | Required | | Modify behavior | Required | If behavior changes | | Bug fix | Required | If regression risk | | Refactor | Required | Not needed |{{IO_CONTRACT}}对于 CLI 工具或 API## I/O contract - **stdout** is data — JSON, structured output, machine-readable. - **stderr** is everything else — progress, warnings, hints. - Never mix them. Mixing corrupts pipe chains.{{GENERATED_ARTIFACTS_POLICY}}如果项目有构建输出目录dist/、build/、.next/:## Generated artifacts Source-first: edit files in src/, lib/, app/. Generated output in dist/ and build/ is rebuilt — never edit it directly. Stage generated files only for release PRs or when the build output itself is the change.{{SUBSYSTEM_RULES}}如果是单一代码库或具有不同子目录的项目packages/、apps/、cli/## Subsystem rules ### packages/dashboard/ - Never use native browser dialogs. Use shadcn/ui instead. - Use kebab-case for file and folder names.每个子目录一个小节并有不明显的规则。阅读子目录中现有的 AGENTS.md 获取线索。{{ARCHITECTURE_DECISIONS}}1-3 个不明显的选择及其“原因”- **Why structured errors**: AI agents parse stderr fields to decide next actions. Never use bare error strings for user-facing failures. - **Why pnpm**: workspace protocol requires pnpm. npm/yarn wont resolve it.{{DOC_UPDATE_CHECKLIST}}如果项目有多个文档界面## Documentation checklist When adding or changing user-facing features, update ALL: 1. cli/src/output.rs — help output 2. README.md — options table, examples 3. docs/ — MDX pages 4. Inline doc comments in source{{INTENT_ROUTING_TABLE}}如果项目有多个入口点、工具或技能## Entrypoints by intent | Intent | Entrypoint | |--------|-----------| | Reproduce from README | ai-research-reproduction | | Environment setup | env-and-assets-bootstrap |将用户目标映射到正确的入口点。{{ERROR_TAXONOMY}}对于具有结构化错误的 CLI/API 项目## Error types | Failure | Constructor | |---------|------------| | Invalid flag/arg | errs.NewValidationError(...).WithParam(--flag) | | Network failure | errs.NewNetworkError(...) | | API error | Return as-is — never re-wrap |{{WRITING_STYLE_GUIDE}}对于生成文档或面向人工智能内容的项目## Writing style - Structure: H2/H3 hierarchy, short paragraphs (2-4 sentences) - Tone: direct, instructional, second person - Clarity: active voice, specific over vague, one idea per section - Budget: challenge each paragraph — does it justify its token cost?{{GOTCHAS}}如果存在特定平台的问题Windows、NTFS、Docker、沙箱:## Gotchas - npx vite build hangs on NTFS — use node node_modules/vite/bin/vite.js build - Server startup takes 30-60s — dont assume failure immediately{{SSH_TROUBLESHOOTING}}仅当 git remote 使用 SSHgitgithub.com时## Git SSH troubleshooting If Git fails with sign_and_send_pubkey or Permission denied: - **Do NOT** switch remotes to HTTPS or retry repeatedly. - Ask the user to ensure their SSH agent is available and unlocked.{{TASK_GUIDES}}1-3 个可重复操作的分步指南。每个指南 3-4 步。{{CONTRIBUTION_GUARDRAILS}}如果存在.github/CONTRIBUTING.md或 PR 模板## Contribution guardrails - Issue-first: open an issue before a PR unless youre a maintainer. - AI agents must disclose AI assistance in PR descriptions. - Unsolicited PRs from non-maintainers may be closed without review.{{VERSIONING_POLICY}}如果项目有多个独立版本的组件## Versioning | Component | Version file | Bump on | |-----------|-------------|---------| | Root | package.json | Breaking changes | | Skills | skills/*/SKILL.md | Any change (unbumped invisible) | Do not bump versions in feature PRs — versioning is a release step.{{RELEASING_SECTION}}编号步骤。仅当存在发布/发布/部署脚本时。{{DOC_IMPORTS}}如果项目已有现有文档CONTRIBUTING.md、docs/*.md、风格指南使用import引用它们而不是重复内容。格式 Detailed docs: CONTRIBUTING.md, docs/best_practices.mdimport用于文档代理始终应将其纳入上下文约定、模式、样式规则。纯 Markdown 链接[Topic](path)对文档来说只偶尔需要。警告大规模导入如果文档超过约300行约1500个标记请标记它“⚠️ 文件过大 — 考虑仅导入关键部分。”不要复制项目文档中已经存在的内容。{{RELEASING_SECTION}}编号步骤。仅当存在发布/发布/部署脚本时。{{RULE_FILE_LINKS}}每个生成的规则文件一个链接。仅在完整模式下。{{CODEGRAPH_SECTION}}仅当.codegraph/存在时。{{CLAUDE_MD_NOTE}}如果检测到 Claude Code存在.claude/目录或CLAUDE.md文件也请在项目根目录生成一个简化的CLAUDE.md使用assets/claude.md。AGENTS.md 是通用标准——CLAUDE.md 只指向它并在存在任何 Claude 特定配置时添加这些配置。生成后限制300 行软上限如果生成的 AGENTS.md 超过 300 行发出警告并建议将内容移动到.agents/rules/或现有项目文档中并使用import。500 行硬上限绝不超过。将内容移到规则文件或引用现有文档。
