Generate CLAUDE.md

Create a minimal, well-structured CLAUDE.md file through an interactive conversation.

Important Guidelines

• Always use AskUserQuestion tool when asking the user anything
• Keep it minimal — CLAUDE.md loads on every request, so only include what's essential
• One question at a time — don't overwhelm with multiple questions
• Use MUST/NEVER/ALWAYS keywords — for unambiguous rules

Core Principle

Models can reliably follow ~150-200 instructions. Every token in CLAUDE.md loads on every request. Only include:

• Project identity (1 sentence)
• Tech stack declaration
• Tooling with MUST/NEVER rules
• Critical guardrails
• Pointers to docs/skills

Everything else should be progressive disclosure (separate docs) or skills (loaded on-demand).

Process

Step 1: Check for Existing Configuration

Check if CLAUDE.md or AGENTS.md exists in the project root.

Also check if package.json exists to help infer tech stack.

If CLAUDE.md or AGENTS.md exists, use AskUserQuestion:

I found existing agent configuration:
- CLAUDE.md: [exists/missing]
- AGENTS.md: [exists/missing]

Would you like to:
1. Start fresh (replace)
2. Audit and improve existing file
3. Cancel

(Choose 1, 2, or 3)

If option 2, read the existing file and use the agents-md audit workflow. If option 3, stop here.

If no files exist, proceed to Step 2.

Step 2: Gather Project Identity

Use AskUserQuestion:

Let's set up your CLAUDE.md file.

**Describe your project in one sentence.**

What does it do and who is it for?

(Example: "A B2B SaaS platform for construction companies to manage projects and crews.")

Step 3: Gather Tech Stack

If package.json exists, read it first to understand the dependencies.

Use AskUserQuestion:

**What's your tech stack?**

Based on your package.json, I see: [summarize what you found, or "no package.json found"]

Please confirm or describe:
- Frontend: (framework, meta-framework)
- Backend: (API approach)
- Database: (database + ORM)
- Styling: (CSS approach)

Step 4: Gather Tooling

Use AskUserQuestion:

**What package manager does this project use?**

1. pnpm
2. npm
3. yarn
4. bun

(Choose 1-4)

After they respond, use AskUserQuestion:

**What do you use for formatting/linting?**

1. Biome
2. ESLint + Prettier
3. ESLint only
4. Other (please specify)

(Choose 1-4)

After they respond, use AskUserQuestion:

**What are your common dev commands?**

List commands you run frequently (dev server, build, test, database, etc.)

(Example: "pnpm dev, pnpm build, pnpm test, pnpm db:push")

Step 5: Gather Guardrails

Use AskUserQuestion:

**Is this a multi-tenant application?**

(Where each customer/org has isolated data that must be filtered)

1. Yes - queries must filter by tenant/org ID
2. No - single tenant or public data

(Choose 1 or 2)

After they respond, use AskUserQuestion:

**Are there any other critical rules that must NEVER be violated?**

Security, compliance, or code quality rules that apply to every task.

(Examples: "Never use any type", "Always validate user input", or "None")

Step 6: Gather Documentation Pointers

Use AskUserQuestion:

**Do you have existing documentation the agent should know about?**

List paths to architecture docs, API docs, or other important files.

(Example: "docs/architecture.md, docs/api.md" or "None yet")

Step 7: Generate CLAUDE.md

Create the file based on gathered information.

Template

# Project Context

## Identity
[Single sentence from Step 2]

## Tech Stack
- Frontend: [from Step 3]
- Backend: [from Step 3]
- Database: [from Step 3]
- Styling: [from Step 3]

## Tooling
- MUST use [package_manager] (NEVER [alternatives])
- MUST use [formatter] for formatting

## Commands
- `[cmd]` - [description]
- `[cmd]` - [description]

## Guardrails
[MUST/NEVER/ALWAYS rules from Step 5]

## More Information
[Documentation pointers from Step 6]
- Run `/skills` to see available patterns and workflows

Generation Rules

1. Skip empty sections — don't include sections with no content
2. Use MUST/NEVER for tooling — "MUST use pnpm (NEVER npm or yarn)"
3. Use MUST/ALWAYS/NEVER for guardrails — security and compliance rules
4. Keep commands minimal — only the most common daily commands
5. Always add — "NEVER commit .env files or secrets" to guardrails

Step 8: Confirm and Write

Show the generated content to the user and use AskUserQuestion:

Here's your CLAUDE.md:

[Show the generated content]

Would you like to:
1. Write this to CLAUDE.md
2. Make changes first
3. Cancel

(Choose 1-3)

If option 1, write the file. If option 2, ask what they'd like to change.

Step 9: Post-Setup

After creating the file, use AskUserQuestion:

✓ Created CLAUDE.md

Would you like to create a symlink to AGENTS.md for compatibility with other tools?

1. Yes - create symlink
2. No - just CLAUDE.md is fine

(Choose 1 or 2)

If yes, run: ln -s CLAUDE.md AGENTS.md

Then output skill recommendations:

Based on your stack, consider installing these skill plugins:

[List relevant plugins based on their tech stack]

- core: Universal coding standards
- platform-frontend / tech-react: React patterns
- platform-backend / tech-trpc: tRPC patterns
- platform-database / tech-drizzle: Drizzle patterns
- platform-testing / tech-vitest: Testing patterns

Run: claude /plugin install github:ravnhq/ai-toolkit/plugins/[name]

Tips

• If the user provides brief answers, that's fine — the CLAUDE.md can be expanded later
• If they want to skip a section, omit it rather than adding placeholders
• Encourage minimal over comprehensive — less is more for CLAUDE.md
• The agents-md skill can audit and improve the file later