109 lines
3.6 KiB
Markdown
109 lines
3.6 KiB
Markdown
|
---
|
|||
|
|
name: generate-agents-md
|
|||
|
|
description: "Generate or update AGENTS.md for the current project. Use when user asks to create project guidelines, initialize AGENTS.md, standardize project conventions, or says '生成 AGENTS.md', '初始化项目规范'."
|
|||
|
|
system: true
|
|||
|
|
category: Development
|
|||
|
|
allowed-tools: ["read_file", "write_file", "run_shell", "list_directory"]
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# Generate AGENTS.md — 项目开发规范生成器
|
|||
|
|
|
|||
|
|
> **AGENTS.md** 是 AI 编码 Agent 的行业标准项目指引文件（[agents.md](https://agents.md/)），
|
|||
|
|
> 被 Cursor、Codex、Copilot、Jules、Windsurf、Aider、opencode 等 20+ 工具支持。
|
|||
|
|
> 一份文件，所有 AI 工具通用。
|
|||
|
|
|
|||
|
|
## When to Use
|
|||
|
|
|
|||
|
|
- 用户说"生成 AGENTS.md"、"初始化项目规范"、"创建项目指引"
|
|||
|
|
- 用户开始用 OpenAkita 开发一个新项目，还没有 AGENTS.md
|
|||
|
|
- 用户说"帮我规范这个项目"、"让 AI 更好地理解这个项目"
|
|||
|
|
|
|||
|
|
## Workflow
|
|||
|
|
|
|||
|
|
### Step 1: 扫描项目结构
|
|||
|
|
|
|||
|
|
使用 `list_directory` 和 `read_file` 收集以下信息：
|
|||
|
|
|
|||
|
|
1. **项目根文件**：检查 `package.json`、`pyproject.toml`、`Cargo.toml`、`go.mod`、`pom.xml`、`Gemfile`、`composer.json` 等，识别语言和框架
|
|||
|
|
2. **README.md**：读取项目描述和现有文档
|
|||
|
|
3. **配置文件**：`.eslintrc*`、`ruff.toml`、`pyproject.toml [tool.ruff]`、`.prettierrc`、`tsconfig.json` 等代码风格配置
|
|||
|
|
4. **CI/CD**：`.github/workflows/`、`.gitlab-ci.yml`、`Jenkinsfile` 等
|
|||
|
|
5. **测试**：`tests/`、`__tests__/`、`spec/`、`test/` 目录；`jest.config.*`、`vitest.config.*`、`pytest.ini`、`conftest.py` 等
|
|||
|
|
6. **目录结构**：顶层目录布局，识别 monorepo（`apps/`、`packages/`、`workspaces`）
|
|||
|
|
7. **现有 AGENTS.md**：如果已存在，读取后在其基础上更新
|
|||
|
|
|
|||
|
|
### Step 2: 生成 AGENTS.md
|
|||
|
|
|
|||
|
|
按以下模板结构生成，**只写与项目相关的段落**，省略不适用的部分：
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
# [Project Name]
|
|||
|
|
|
|||
|
|
[一句话描述项目做什么]
|
|||
|
|
|
|||
|
|
## Tech Stack
|
|||
|
|
|
|||
|
|
- Language: [语言及版本]
|
|||
|
|
- Framework: [框架]
|
|||
|
|
- Package Manager: [包管理器]
|
|||
|
|
|
|||
|
|
## Dev Environment Setup
|
|||
|
|
|
|||
|
|
[环境准备步骤，如 Python 版本、Node 版本、依赖安装命令]
|
|||
|
|
|
|||
|
|
## Build & Run
|
|||
|
|
|
|||
|
|
[构建、启动、热重载等命令]
|
|||
|
|
|
|||
|
|
## Testing
|
|||
|
|
|
|||
|
|
[测试框架、运行命令、覆盖率要求]
|
|||
|
|
|
|||
|
|
## Code Style
|
|||
|
|
|
|||
|
|
[lint 工具、格式化工具、关键规则]
|
|||
|
|
|
|||
|
|
## Project Structure
|
|||
|
|
|
|||
|
|
[关键目录说明，不要列出每个文件]
|
|||
|
|
|
|||
|
|
## Architecture Notes
|
|||
|
|
|
|||
|
|
[核心架构设计、数据流、重要模块关系]
|
|||
|
|
|
|||
|
|
## PR & Commit Conventions
|
|||
|
|
|
|||
|
|
[提交信息格式、分支策略]
|
|||
|
|
|
|||
|
|
## Known Gotchas
|
|||
|
|
|
|||
|
|
[新手容易踩的坑、特殊约定]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Step 3: 写入文件
|
|||
|
|
|
|||
|
|
使用 `write_file` 写入到项目根目录的 `AGENTS.md`。
|
|||
|
|
|
|||
|
|
### Step 4: Monorepo 检查
|
|||
|
|
|
|||
|
|
如果检测到 monorepo 结构（`apps/`、`packages/`、`services/` 等子项目），**询问用户**是否需要为子项目也生成嵌套的 AGENTS.md。子项目的 AGENTS.md 只写该子项目特有的内容，不重复根级内容。
|
|||
|
|
|
|||
|
|
## Important Rules
|
|||
|
|
|
|||
|
|
- **控制长度**：AGENTS.md 建议 150 行以内，不要写成完整文档
|
|||
|
|
- **只写有用的**：不要填充模板中每个段落，省略不适用的
|
|||
|
|
- **面向 AI Agent**：内容是给 AI 看的，不需要"入门教程"级别的解释
|
|||
|
|
- **可执行的命令**：构建、测试、lint 等必须是可以直接复制执行的命令
|
|||
|
|
- **不要暴露敏感信息**：不要写 API key、密码、内部 URL 等
|
|||
|
|
- **中英文皆可**：跟随项目的主要语言（README 是中文就用中文）
|
|||
|
|
|
|||
|
|
## Examples
|
|||
|
|
|
|||
|
|
用户说："帮我生成 AGENTS.md"
|
|||
|
|
|
|||
|
|
→ 执行 Step 1-4，扫描项目后生成文件。
|
|||
|
|
|
|||
|
|
用户说："更新一下 AGENTS.md"
|
|||
|
|
|
|||
|
|
→ 先读取现有 AGENTS.md，结合项目当前状态更新过时的内容。
|