CLAUDE.md + tools.md: The Two Files Every AI Project Needs

The problem

Most AI project setup files try to do too much.

One file says:

• Use our Button before inventing a new one
• This repo uses pnpm, not npm
• Never touch production data
• The app is Astro on Vercel
• Our visual style is calm, editorial, and token-driven
• Run npm run build before a PR
• Do not add Tailwind if it is not already installed

Some of those are behavior rules. Some are tool facts. Some are design standards. When you mix everything together, the file grows into a wall of text and the agent starts ignoring the important parts.

The fix is boring and very effective: split the context into two files.

---

The split

Criterion	CLAUDE.md Best pick Behavior and project rules	tools.md Tools and commands	Prompt only Temporary context
Design system rules	✓	—	Only for one task
Token and component conventions	✓	—	Only for one task
Package manager	Reference tools.md	✓	Easy to forget
Build and test commands	Reference tools.md	✓	Easy to forget
Allowed and blocked actions	✓	—	Only for one task
Deployment target	Reference tools.md	✓	Only if relevant

Use CLAUDE.md for things that are true about the project culture:

• What the design system is
• Which components to prefer
• Which token naming pattern is valid
• What Claude may do without asking
• What Claude must never do
• Common failures to avoid

Use tools.md for things that are true about the project machinery:

• Framework
• Package manager
• UI library
• Testing tools
• Build commands
• Deployment target
• Dependency rules
• Known integrations

This makes both files shorter. Shorter files get read. Read files change behavior.

---

The minimum useful version

If you only have 15 minutes, create this:

# tools.md

## Stack

- Framework: [Astro / Next.js / React / etc.]
- Package manager: [npm / pnpm / yarn / bun]
- UI: [custom components / shadcn/ui / Radix / etc.]
- Styling: [CSS / Tailwind / Panda / etc.]
- Deployment: [Vercel / Netlify / GitHub Pages / etc.]

## Commands

- Install: [command]
- Dev: [command]
- Build: [command]
- Test: [command]
- Lint: [command]

## Rules

- Match the package manager in this file.
- Use existing package scripts before inventing commands.
- Do not add dependencies without explaining why.
- If this file conflicts with package.json or lockfiles, inspect the repo first.

Then add one line to CLAUDE.md:

Before changing tooling, dependencies, tests, package scripts, or deployment
configuration, read ./tools.md and follow it as the source of truth.

That line is the bridge.

---

How the two files work together

1. 01

   User asks

   The task starts in Claude, Codex, Cursor, or another agent.

2. 02

   Rules load

   CLAUDE.md tells the agent what good work means here.

3. 03

   Tools load

   tools.md tells the agent which stack, commands, and dependencies exist.

4. 04

   Agent acts

   The answer uses the right components and the right commands.

The difference shows up immediately.

Without tools.md, an agent may say:

Run yarn dev.
Install @supabase/auth-helpers-nextjs.
Deploy with Netlify.

With tools.md, the same agent can see:

This repo uses npm, Astro, Better Auth, and Vercel.
Use npm run dev.
Do not add deprecated Supabase packages.
Run npm run build before final review.

The quality jump is not magic. It is context.

---

What to keep out

Do not turn tools.md into a second CLAUDE.md.

Keep these out of tools.md:

• Brand voice
• Visual taste
• Design principles
• Long component explanations
• Personal preferences
• Failure logs
• Prompt templates

Put those in CLAUDE.md, .claude/rules/, a skill, or a project context folder.

Keep these out of CLAUDE.md:

• Every dependency
• Full package script lists
• Tool version histories
• Long setup instructions
• Deployment environment details

Put those in tools.md, README, or dedicated docs.

---

When to update the files

Update tools.md in the same PR when:

• You change package manager
• You add or remove a major dependency
• You change build, test, lint, or deploy commands
• You move from one platform to another
• You add a new AI-relevant integration, like Playwright, Storybook, MCP, or Tokens Studio

Update CLAUDE.md when:

• The agent makes the same mistake twice
• Your design system rule changes
• A component convention changes
• You add a new permission boundary
• You learn a better way to describe your taste or review criteria

The files are not documentation for humans only. They are operating instructions for your agents.

---

Exercise

Create the two-file setup

20 min

1. Generate tools.md

   Open the Tools.md Generator. Answer the questions or paste your package.json. Save the output as tools.md at the root of your repo.

   • It names the framework, package manager, UI library, testing, and deployment target
   • It includes the exact install, dev, build, test, and lint commands
   • It is assistant-neutral, so Claude, Codex, Cursor, and Windsurf can all use it

2. Link it from CLAUDE.md

   Open your CLAUDE.md. Add the bridge line from this guide. If you do not have CLAUDE.md yet, create the smallest useful version with project summary, preferences, capabilities, and failure log.

   • CLAUDE.md tells the agent to read tools.md before changing tools or commands
   • Tool facts are not duplicated across both files
   • A fresh AI session can answer: what project is this, and how do I run it?