agent-config

User Input

$ARGUMENTS

• create

  - Create new file from scratch

• update

  - Improve existing file

• audit

  - Analyze and report on current file quality
• A specific path (e.g.,

  src/api/CLAUDE.md

  for directory-specific instructions)

Step 1: Determine Target File

• Bash commands Claude cannot guess
• Code style rules that differ from defaults
• Testing instructions and preferred test runners
• Repository etiquette (branch naming, PR conventions)
• Architectural decisions specific to the project
• Developer environment quirks (required env vars)
• Common gotchas or non-obvious behaviors

• Specialized assistant definitions
• Tool permissions for each agent
• Model preferences (opus, sonnet, haiku)
• Focused instructions for isolated tasks

CLAUDE.md Guidelines

Core Principle

What to Include

Quality Test

Example Format

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

File Locations

• Home folder (

  ~/.claude/CLAUDE.md

  ): Applies to all Claude sessions
• Project root (

  ./CLAUDE.md

  ): Check into git to share with your team
• Local only (

  CLAUDE.local.md

  ): Add to

  .gitignore

  for personal overrides
• Parent directories: Useful for monorepos where both

  root/CLAUDE.md

  and

  root/foo/CLAUDE.md

  are pulled in automatically
• Child directories: Claude pulls in child CLAUDE.md files on demand

Import Syntax

@path/to/import

See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

Emphasis for Critical Rules

AGENTS.md Guidelines

Agent Definition Format

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling

Provide specific line references and suggested fixes.

Required Fields

• name: Identifier to invoke the agent
• description: What the agent does (helps Claude decide when to use it)
• tools: Comma-separated list of allowed tools (Read, Grep, Glob, Bash, Edit, Write, etc.)

Optional Fields

• model: Preferred model (opus, sonnet, haiku)

Best Practices for Agents

1. Keep agent instructions focused on a single domain
2. Be specific about what the agent should look for
3. Request concrete output formats (line references, specific fixes)
4. Limit tool access to what's actually needed

Execution Flow

For

create

or default:

1. Ask which file type (CLAUDE.md or AGENTS.md) if not specified
2. Analyze the project:
   • Check for existing files at standard locations
   • Identify technology stack, project type, development tools
   • Review README.md, CONTRIBUTING.md, package.json, etc.
3. Draft the file following guidelines above
4. Present draft for review
5. Write to appropriate location after approval

For

update

:

1. Read existing file
2. Audit against best practices
3. Identify:
   • Content to remove (redundant, obvious, style rules)
   • Content to condense
   • Missing essential information
4. Present changes for review
5. Apply changes after approval

For

audit

:

1. Read existing file
2. Generate a report with:
   • Assessment of content quality
   • List of anti-patterns found
   • Percentage of truly useful vs redundant content
   • Specific recommendations for improvement
3. Do NOT modify the file, only report

Anti-Patterns to Avoid

• Code style guidelines (use linters/formatters)
• Generic best practices Claude already knows
• Long explanations of obvious patterns
• Copy-pasted code examples
• Information that changes frequently
• Instructions for specific one-time tasks
• File-by-file codebase descriptions

Notes

• Run

  /init

  to generate a starter CLAUDE.md based on current project structure
• Treat CLAUDE.md like code: review it when things go wrong, prune it regularly
• Check CLAUDE.md into git so your team can contribute
• The file compounds in value over time as you refine it