create-agents-file by kvnwolf/devtools

Create a concise AGENTS.md that gives AI coding agents the minimum context needed to work effectively in this project. The file loads on every session — every line competes with conversation history for context window space.

Rules

Every question directed at the user MUST use the AskUserQuestion tool. Never assume or silently decide on behalf of the user.
Execute steps strictly in order, one at a time.
Skip steps whose output already exists. If AGENTS.md exists with all sections populated, skip to the review step. If it exists but is incomplete, fill in the gaps.

Step 1: Explore the codebase

Launch two Explore agents in parallel. Agents must use Glob, Grep, and Read exclusively — never Bash commands like ls, cat, find, head, or tail.

Agent A — Project identity (quick):

package.json — name, description, dependencies, devDependencies, scripts
Lock files — bun.lock → bun, pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm
README or existing documentation
Existing AGENTS.md / CLAUDE.md
Top-level config files (tsconfig, eslint/biome, vitest/jest, playwright, tailwind, etc.)

Agent B — Codebase patterns (medium):

Source directory structure and architectural patterns (monorepo? app router? API layer?)
Testing setup — frameworks, project configs, co-location patterns, how different test types are run
Key conventions — imports, path aliases, naming, file organization, linting
Environment variable patterns
Deployment setup (if obvious from config)
Any non-standard tooling or scripts that an agent would need to know

Checklist — do not proceed until all pass:

Both agents returned with findings
Package manager identified
Core stack identified
Key scripts/commands cataloged

Step 2: Present findings and interview

Present a concise summary of what was discovered. Then use AskUserQuestion to fill in anything that could NOT be inferred:

Project description (if not clear from README/package.json)
Conventions or preferences not visible in the codebase
Anything the user considers essential for agents to know

Do not ask about things already discovered. Keep questions focused and specific.

Step 3: Write AGENTS.md

Follow this template exactly. All five sections are required:

# <Project Name>

<One or two sentences describing what the project does.>

## Tech Stack

<Comma-separated list of core frameworks and libraries. Include versions only when they matter (e.g., major version differences change APIs).>

## Package Manager

<npm | bun | pnpm | yarn>

## Commands

| Command | Description |
|---------|-------------|
| `<command>` | <what it does> |

## Conventions

<Bullet points documenting stable, project-wide patterns. Each entry should be
1-2 lines and explain WHY when the reasoning isn't obvious. Only include rules
that apply globally — domain-specific patterns belong in skills, not here.>

What belongs in Commands

All scripts from package.json that an agent would use: build, test, lint, typecheck, dev, etc.
Non-standard or project-specific commands that the agent wouldn't guess
Prefer file-scoped variants when available (e.g., vitest run src/path/file.test.ts) — they're faster and cheaper

What belongs in Conventions

Patterns that repeat across the entire codebase and that the agent would otherwise have to rediscover every session
Stable decisions that prevent redundant questions (e.g., preferred UI library, state management strategy)

Deduplication with installed skills

Before writing conventions, scan all skill descriptions available in the system prompt. If a skill already covers a pattern or convention (e.g., a testing skill already defines test patterns, a component skill already defines component conventions), do NOT repeat that knowledge in AGENTS.md. The convention section should only contain what is NOT covered by any installed skill.

What does NOT belong in either section

Knowledge already covered by an installed skill
File trees or directory structures — they go stale immediately
Generic framework knowledge — the agent already knows how React, Prisma, etc. work
Lengthy explanations — keep entries to 1-2 lines
Rules without reasoning — "use named exports" is weaker than "use named exports — default exports lose the symbol name in refactoring tools and re-exports"

Examples

Example 1 — Next.js app with Prisma:

# Acme Dashboard

Internal analytics dashboard for tracking product metrics and user engagement.

## Tech Stack

Next.js 15 (App Router), Prisma (PostgreSQL), TailwindCSS, shadcn/ui, Vitest, Playwright.

## Package Manager

pnpm

## Commands

| Command | Description |
|---------|-------------|
| `pnpm dev` | Start dev server |
| `pnpm build` | Production build |
| `pnpm lint` | ESLint check |
| `pnpm typecheck` | Type check with tsgo |
| `pnpm test` | Run Vitest unit tests |
| `pnpm e2e` | Run Playwright e2e tests |
| `pnpm db:push` | Push Prisma schema to database |
| `pnpm db:studio` | Open Prisma Studio |

## Conventions

- Named exports only — default exports lose the symbol name in refactoring tools and re-exports
- Path aliases: `@/*` → `src/*`, `@db/*` → `prisma/*`
- Environment variables validated with `@t3-oss/env-nextjs` in `src/env.ts`
- Biome for linting and formatting (not ESLint/Prettier)

Example 2 — Express API with TypeScript:

# Payments API

REST API for processing payments, managing subscriptions, and handling webhooks.

## Tech Stack

Express, TypeScript, Drizzle ORM (PostgreSQL), Zod, Vitest.

## Package Manager

npm

## Commands

| Command | Description |
|---------|-------------|
| `npm run dev` | Start dev server with tsx watch |
| `npm run build` | Compile TypeScript |
| `npm test` | Run Vitest |
| `npm run lint` | ESLint check |
| `npm run typecheck` | tsc --noEmit |
| `npm run db:migrate` | Run Drizzle migrations |
| `npm run db:generate` | Generate Drizzle schema |

## Conventions

- All routes in `src/routes/` — one file per resource (e.g., `payments.ts`, `subscriptions.ts`)
- Validation with Zod schemas co-located next to route handlers
- Error responses follow RFC 7807 (Problem Details) format
- All monetary amounts stored as cents (integers) — never floating point

Writing principles

Under 80 lines — aim for 40-60. If it's longer, cut.
Only add what the agent doesn't already know.
No file trees. Describe capabilities, not file paths.
Rules with reasoning. Explain WHY, not just WHAT.

Checklist — do not proceed until all pass:

AGENTS.md has all five sections: description, tech stack, package manager, commands, conventions
File is under 80 lines
Commands table includes all relevant scripts from package.json
Conventions are project-wide only — no domain-specific rules, no commands
Every convention includes reasoning (or the reasoning is self-evident)
No generic framework knowledge documented

Step 4: Create CLAUDE.md symlink

If AGENTS.md was created/updated but CLAUDE.md does not exist, create a symlink:

ln -s AGENTS.md CLAUDE.md

If CLAUDE.md already exists as a regular file (not a symlink), ask the user whether to replace it with a symlink to AGENTS.md or keep it as-is.

Step 5: Review with the user

Present the complete AGENTS.md content to the user and ask if they want to change anything. Iterate until confirmed.