Agents Md Gen

AGENTS.md 生成器

为代码仓库生成专业、结构化的 AGENTS.md 文件，使 Codex/LLM 能高效理解和操作项目。

工作流

1. 项目扫描

执行以下探测命令收集项目元信息：

# 语言和框架检测
find . -maxdepth 3 -name "*.py" -o -name "*.ts" -o -name "*.go" -o -name "*.rs" | head -20
cat package.json 2>/dev/null | head -30
cat pyproject.toml 2>/dev/null | head -30
cat Cargo.toml 2>/dev/null | head -30
cat go.mod 2>/dev/null | head -10

# 构建工具
ls Makefile Dockerfile docker-compose.yml .github/workflows/ 2>/dev/null

# 测试框架
rg -l "pytest|jest|vitest|cargo test|go test" --type-add 'code:*.{py,ts,js,rs,go}' -t code 2>/dev/null | head -5

# 目录结构（2层）
find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/vendor/*' | sort

# 已有 AGENTS.md
find . -name "AGENTS.md" -type f

根据项目规模调整深度，大型项目（>100 文件）只扫描 maxdepth 2。

2. 信息提取与分析

从扫描结果中提取：

• 主语言：文件扩展名统计最多的语言
• 框架：package.json/pyproject.toml/Cargo.toml 中的依赖
• 构建命令：Makefile targets、scripts 字段、cargo commands
• 测试命令：test 配置、测试文件模式
• CI 配置：.github/workflows、Jenkinsfile、.gitlab-ci.yml
• 代码风格：lint 配置文件（.eslintrc、ruff.toml 等）
• 目录语义：src/lib/test/cmd/api 等目录的用途推断

3. 生成 AGENTS.md

按以下结构输出，根据实际情况裁剪：

# AGENTS.md

## 项目概述
- 一句话说明项目用途
- 主语言 + 框架 + 运行时版本

## 目录结构
- `src/` — 源码入口
- `lib/` — 核心库代码
- `tests/` — 测试文件
- `cmd/` — CLI 入口（如适用）

## 构建与运行
- 安装：`npm install` / `pip install -e .` / `cargo build`
- 启动：`npm run dev` / `python -m app`
- 构建：`npm run build` / `cargo build --release`

## 测试
- 运行全部：`npm test` / `pytest`
- 运行单个：`pytest tests/test_api.py::test_login`
- 覆盖率：`pytest --cov`

## 代码规范
- Lint：`npm run lint` / `ruff check .`
- 格式化：`npm run format` / `black .`
- 提交前检查：`pre-commit run --all-files`

## CI/CD
- 平台：GitHub Actions / GitLab CI
- 流程：lint → test → build → deploy
- 分支策略：main 保护 + PR review

## 注意事项
- 不要修改的文件/目录
- 特殊配置或约定
- 已知的技术债或待重构区域

4. 质量检查

生成后验证：

• 所有提到的命令在项目中确实可用
• 目录结构描述与实际一致
• 没有包含过时或不存在的工具
• 语言简洁，无冗余解释

输出格式

最终文件写入项目根目录 AGENTS.md。内容应：

• 控制在 100 行以内
• 使用中文或英文（与项目文档语言一致）
• 每个 section 只包含实际存在的工具/配置
• 命令可直接复制执行

边界情况

• 单文件脚本：只生成概述 + 运行方式，跳过目录结构
• Monorepo：为根目录和每个 package 各生成一个 AGENTS.md，根目录的列出子包导航
• 已有 AGENTS.md：读取现有内容，在其基础上优化，保留用户自定义部分
• 无 CI 配置：跳过 CI/CD section，不臆造