gm-agent-docs

gm-agent-docs

Generate high-quality CLAUDE.md and AGENTS.md for any project.

Core Principles

A good agent md document = an operations manual, not human documentation.

1. Command-first — every instruction must be able to answer "what command proves it was done right"
2. Code examples > prose descriptions — one snippet beats three paragraphs of explanation
3. Concise — within 100 lines (upper limit 200; beyond 300 the agent loses signal)
4. Only write what the agent cannot infer — standard syntax and library usage do not need to be written
5. Three-tier boundaries — ✅ must do / ⚠️ ask first / 🚫 never do
6. Continuous evolution — every time the agent makes a preventable mistake, add a rule

Process

Step 1: Analyze the project

Scan the project root directory and collect information across 6 core areas:

Area	Scan target	Output
Commands	package.json scripts / Makefile / pyproject.toml / Cargo.toml / go.mod	Specific commands for build, test, lint, and start
Testing	jest.config / vitest.config / pytest.ini / test directory	Framework, how to run, coverage requirements
Project structure	Top-level directories + framework conventions	Responsibilities of key directories, architectural patterns
Code style	eslint / prettier / ruff / .editorconfig + the last 10 commits	Naming conventions, formatting rules (shown with code examples)
Git workflow	The last 20 commit messages + branch naming	Commit format, branching strategy
Boundaries	.gitignore / CI configuration / sensitive files	Files that must not be touched, operations that require approval

Additional scans (large projects):

• docs/ / ADR/ / specs/ → generate a documentation index table
• monorepo subpackages → generate directory-level scoping suggestions
• CI/CD configuration → extract deployment constraints

Output an analysis summary for the user to confirm, then proceed to generation.

Step 2: Generate CLAUDE.md

The 6 sections that must be included (in this order):

# 项目名

一句话说明（技术栈 + 版本，要具体）。

## 常用命令

直接可执行的 shell 命令，含 flags。按频率排序：
- 开发服务器
- 运行测试
- lint / format
- 构建 / 部署

## 写代码时

- 架构约束（目录职责、依赖方向）
- 代码风格（用 ✅/❌ 代码示例展示，不用文字描述）
- 验证命令

## 完成标准

编号列表，每条 = 具体命令 + 期望退出码：
1. `命令` 退出码 0
2. `命令` 退出码 0
3. commit message 符合格式

## 卡住时

- 具体场景 → 具体操作
- 连续失败 3 次 → 停下来报告，不要继续尝试
- 绝不：列出禁止的破坏性操作

## 参考文档（可选，大型项目才加）

| 文件 | 何时读取 |
|------|---------|
| `docs/xxx.md` | 做 xxx 时 |

Content that must not appear:

• Long prose passages, project history
• Vague wording such as "please note", "suggest", "be careful"
• Information the agent can infer from the code
• Sensitive information such as API keys and passwords
• Contradictory priorities with no ordering

Step 3: Generate AGENTS.md

Write only one line:

See [CLAUDE.md](./CLAUDE.md) for all project instructions.

Step 4: Output and confirmation

1. Show the generated CLAUDE.md to the user for review
2. Write to the file after the user confirms
3. If a CLAUDE.md already exists, show the diff and then confirm before overwriting

Example output

Next.js project

# my-app

Next.js 14 全栈应用，App Router + Prisma + PostgreSQL + TypeScript。

## 常用命令

pnpm dev          # localhost:3000
pnpm build        # 生产构建
pnpm test         # vitest
pnpm lint         # eslint + prettier check

## 写代码时

- 页面放 `app/`，API 路由放 `app/api/`
- 数据库操作只通过 `lib/db.ts`
- 服务端组件默认，客户端组件加 `'use client'`

```typescript
// ✅
export async function getUser(id: string): Promise<User> {
  return db.user.findUniqueOrThrow({ where: { id } });
}

// ❌
export async function getUser(id) {
  const user = await db.user.findUnique({ where: { id } });
  return user;
}

Completion criteria

1. pnpm build exit code 0
2. pnpm test exit code 0
3. pnpm lint exit code 0
4. commit: type(scope): description

When stuck

• Type error won't fix → pnpm tsc --noEmit view the full error message
• Database conflict → pnpm prisma migrate reset(will clear data, confirm first)
• Never: skip build, modify migrations directly, force push main

### Python 项目

```markdown
# my-service

FastAPI REST API，Python 3.12 + SQLAlchemy + Alembic + PostgreSQL。

## 常用命令

uv run uvicorn app.main:app --reload   # dev server :8000
uv run pytest -v                        # 测试
uv run ruff check .                     # lint
uv run mypy app/ --strict               # 类型检查

## 写代码时

- 路由放 `app/api/`，模型放 `app/models/`
- 所有函数必须有 type hints
- 依赖注入用 `Depends()`

```python
# ✅
async def get_user(user_id: int, db: Session = Depends(get_db)) -> User:
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(status_code=404)
    return user

# ❌
async def get_user(user_id, db):
    return await db.query(User).filter_by(id=user_id).first()

Definition of done

1. uv run ruff check . exit code 0
2. uv run pytest -v exit code 0
3. uv run mypy app/ --strict exit code 0
4. commit: type: description

When stuck

• Tests fail 3 times → stop, paste the full traceback
• migration conflict → alembic downgrade -1 then regenerate
• Never: delete migration files, skip mypy, modify the alembic_version table