agentsmd-generator

Agent Context Generator

你将要做的事

• 🔍 梳理代码仓库的结构，记录遵循 .gitignore 的 tree 输出，并记录自动化入口（如果有 just/make 任务，优先使用）
• 🧭 记录编码约定、目录归属、测试要求和评审工作流，让后续 Agent 能够自信地浏览代码仓库
• 🧩 按照下文规定的章节顺序编写 AGENTS.md 文件，并遵守嵌套目录的作用域规则
• ✅ 加入通用收尾任务：确保重大代码变更后更新 README，并按照常规提交格式总结变更，同时与开发者一起解决所有待确认问题

---

阶段 1 · 了解代码仓库

1. 检查现有的 AGENTS.md
   • 使用 find 的替代方式（glob 或代码仓库树）发现现有文件。确定作用域继承规则，以便更新或扩展，而不是重复创建。
2. 阅读核心文档
   • 浏览 README.md、CONTRIBUTING.md 和其他入门文档，了解项目理念、设置和工作流。
   • 如果存在 docs/ 或 documentation/，请查阅其中值得在 AGENTS.md 中提及的架构或流程参考资料。
3. 调查项目布局
   • 记录主要目录、语言、构建目标和归属（例如，“src/ui 由前端团队维护”）。
   • 检查 plans/、docs/ 或其他知识目录。标出之后要在 AGENTS.md 中引用的必读文件（ADR 索引、架构概览、操作手册）。
4. 构建 Git 感知的目录树
   • 使用带有 --gitignore 标志的 tree 命令（tree ≥ 2.0），隐藏被忽略的路径：tree --gitignore -a -L 3 > tmp/tree.txt。
   • 如果你的 tree 版本不支持 --gitignore，运行 tree -a -L 3 --prune，并手动清理 .gitignore 中注明的被忽略目录；或者通过包管理器安装较新的版本。
   • 将输出记录下来，或在放入 AGENTS.md 之前进行精简（重点展示前 2–3 层，并注明为简洁起见省略了部分细节）。
5. 识别自动化运行器
   • 如果存在 Justfile，运行 just --list（如需查看额外说明，可运行 just --list --unsorted）。
   • 如果存在 Makefile（且不存在 just），运行 make help，或检查伪目标，确定规范任务。
   • 记录推荐用于代码检查、测试、构建、数据同步等的命令。在笔记中标明并链接之后要提及的权威任务名称。
6. 列出工具和环境
   • 列出所需的运行时、包管理器、环境变量、密钥处理方式和本地服务。
   • 记录任何 .env.example、config/ 或密钥文档，以便 Agent 查阅。
7. 明确测试和质量门禁
   • 确定测试套件、覆盖率要求、代码检查、格式化和 CI 工作流。
8. 尽早解决歧义
   • 如果约定、归属或工作流不清楚，请在起草指南之前向开发者提出有针对性的问题。
   • 明确询问现有的 plans/ 或文档目录是权威资料还是已经过时，并确认应参考哪些规范。

结果： 一份结构化笔记，涵盖布局、工具、命令、测试、发布流程、文档参考、待解决的问题和更新要求。

---

阶段 2 · 规划 AGENTS.md 结构

遵循以下主张明确的顺序，让文件保持一致且便于浏览：

1. 标题 — 标题 + 简短的用途说明。
2. 快速概览 — 用表格或项目符号概述（语言、包管理器、关键脚本、CI）。
3. 仓库导览 — 高层级目录映射，说明各目录的职责和所有权提示。
4. 工具与设置 — 所需的运行时、包管理器、环境变量、密钥。
5. 常见任务 — lint/test/build/deploy 命令。优先列出 just 配方，然后是 make 目标，最后是原始命令。
6. 测试与质量 — 何时以及如何运行测试、lint、格式化、覆盖率检查，以及 CI 预期。
7. 工作流要求 — 分支模型、评审规范、功能标记、部署节奏。
8. 文档职责 — 何时更新 README.md、架构图或其他文档。
9. 完成任务 — 每项 Agent 任务都必须遵循的收尾清单。

对于更深层的目录（例如 services/api/），请在顶部添加“范围”说明，明确该目录如何继承父级 AGENTS 指引。起草新的分目录 AGENTS 文件前，务必先与开发者确认，以免重复已有指引或造成不必要的负担。

---

阶段 3 · 编写 AGENTS.md

使用以下模板，并根据项目进行调整：

# Project Agent Guide

> Scope: Root project (applies to all subdirectories unless overridden)

## Quick Facts
- **Primary language:**
- **Package manager:**
- **Entrypoints:**
- **CI/CD:**

## Repository Tour
- `path/` — description & owner

## Tooling & Setup
- Install instructions (per OS)
- Required environment variables (with purpose)
- Secrets management notes

## Common Tasks
- `just <task>` — what it does (preferred)
- `make <target>` — what it does
- Raw command fallback when automation missing

## Testing & Quality Gates
- Unit/integration test commands
- Lint/format commands
- Coverage expectations & thresholds
- CI status command or dashboard link

## Workflow Expectations
- Branch naming and review rules
- Feature toggles or release cadence
- Any approval or ticket linkage requirements

## Documentation Duties
- Update `README.md` when features, setup steps, or developer ergonomics change materially
- List other docs to refresh (architecture, ADRs, etc.)

## Finish the Task Checklist
- [ ] Update relevant docs (& `README.md` if significant changes landed)
- [ ] Summarize changes in conventional commit format (e.g., `feat: ...`, `fix: ...`)

子目录模板（仅在获得开发者批准后使用）

# <Directory Name> Agent Guide

> Scope: ./path/to/directory (inherits root AGENTS.md unless noted)

## Purpose
- What lives here
- Who owns it (team/contact)

## Key Files
- `file_or_folder/` — why it matters

## Common Tasks
- `just <task>` / `make <target>` / command snippets scoped to this directory

## Testing & Quality
- Specific tests, linters, or data fixtures for this directory

## Hand-off Notes
- Docs or runbooks to reference
- Open questions captured during discovery

只有在确认哪些区域需要专门的上下文，以及应强调哪些信息后，才为这些目录创建专属指南。

写作说明：

• 使用直接、可执行的语言。Agent 应逐字遵循命令。
• 说明首选的操作顺序（例如：“始终先运行 just format，再发起 PR”）。
• 提及脚本时，注明相对路径，方便 Agent 快速跳转（例如，scripts/bootstrap.sh）。
• 加入精简的 tree --gitignore 快照（或链接到已保存的文件），让读者快速了解目录布局。
• 在仓库导览中，若存在 plans/、docs/、设计文档或 ADR，请指出其位置。
• 将尚未解答的问题列为待办事项，并在创建任何分目录 AGENTS 指引前与开发者确认。
• 如果项目包含多种语言或平台，请按组件添加子章节，但将全局指引放在前面。

---

阶段 4 · 验证与收尾

1. 自我检查
   • 文件是否遵循 AGENTS 范围规则？（说明继承关系或覆盖规则。）
   • 是否记录了所有关键命令，尤其是自动化入口？
   • 是否明确说明了 README 更新要求？
   • 添加任何分目录 AGENTS 文件前，是否已获得开发者批准，并在文档中注明该批准？
   • “完成任务”清单是否包含常规提交摘要提醒？
2. 格式
   • 确保标题使用标题式大小写，命令用反引号括起，列表简洁。
   • 各章节控制在约 8 个项目符号以内，表格更清晰时则使用表格。
3. 交接摘要
   • 向用户交付 AGENTS.md 时，请包含：
     • 新增或更新的主要章节简述。
     • 确认已包含 README 和常规提交提醒。
     • 后续建议（例如，缺少测试或脚本已过时）。

在仓库缺少 AGENTS 上下文，或现有指引不完整、过时的情况下，使用此技能。目标是为未来的 Agent 留下一份可信的项目地图，涵盖项目工具以及负责任地完成任务的要求。