claude-md-global

Generate or audit a global ~/.claude/CLAUDE.md — your personal defaults for every project.

The global file lives at ~/.claude/CLAUDE.md and applies to ALL projects. Target: ~30 lines maximum.

Ask the user about their preferences Only ask what cannot be inferred. Ask in a single grouped message:

Philosophy (most important):

• "What are your core engineering values? The principles that guide your decisions when there's no clear right answer."

• Prompt with contrasting examples to help them articulate:

• "YAGNI vs. building for extensibility?"

• "Simplicity vs. performance?"

• "Explicit vs. DRY?"

• Target: 3-5 bullet points that are OPINIONATED and SPECIFIC

• Quality test: "Would two reasonable engineers disagree on this?" — if no, it's too generic

Preferences:

• Preferred response language

• Primary language/framework (TypeScript, Python, Go, etc.)

• Package manager preference (pnpm, npm, yarn, bun, uv, etc.)

• Test runner preference (vitest, jest, pytest, etc.)

• Commit convention (conventional commits, other)

Think before writing (critical step) Before generating, evaluate each candidate line against the golden rule:

• "Can the agent discover this on its own?" → if YES, don't include

• "Is this a generic best practice any senior dev knows?" → if YES, don't include

• "Would the agent make the WRONG choice without this?" → if YES, include

Generate the file following these principles

The golden rule: write only what the agent cannot discover on its own.

Include ONLY these sections:

Philosophy (~4 lines)

• The user's core engineering values from step 2

• These shape HOW the agent thinks — they're the tiebreakers for ambiguous decisions

Response language & style (~2 lines)

• Language to respond in

• Communication style (e.g., no unsolicited explanations)

Code conventions (~4 lines)

• Naming conventions (files, variables, components, constants)

• Strictness rules (e.g., strict TypeScript, unknown over any)

• Only conventions the agent would get wrong without guidance

Tools (~3 lines)

• Package manager

• Test runner

• "Run tests after changes" if that's the user's expectation

Git (~3 lines)

• Commit message format

• Key guardrails (no force push, no amend published commits)

Workflow (~3 lines)

• Critical process rules (read before edit, one task at a time)

• Only rules the agent tends to violate

Review and trim (critical step) Read the generated file as if you're paying per token (because the user is). For each line, ask these 3 questions: a) "Would the agent get this wrong without this line?" → if NO, delete b) "Is this already enforced by a linter, type system, or config?" → if YES, delete c) "Can I merge this with another line without losing meaning?" → if YES, merge

Then verify:

• Line count within target (~30 lines, 25-35 acceptable)

• No two lines say the same thing differently

• Every bullet is a COMMAND or CONSTRAINT, not a description

Write the file

• Write to ~/.claude/CLAUDE.md

• Use # headers for sections (no nested headers)

• Use - bullet lists, no numbered lists

• No XML tags, no code blocks, no frontmatter — plain markdown only

Philosophy

• YAGNI: only implement what's needed NOW — no speculative abstractions
• Explicit over DRY: a little repetition is better than the wrong abstraction
• Fix root causes, never band-aid solutions

Language

Always respond in French. Code and commits in English.

Code conventions

• Files: kebab-case | Variables: camelCase | Components: PascalCase
• Strict TypeScript: prefer unknown over any, no implicit returns

Tools

• Package manager: pnpm
• Tests: vitest — run after every change

Git

• Conventional commits: feat(scope): msg, fix:, refactor:, chore:
• Never force push to main

Workflow

• Read files before editing — understand context first
• One task at a time: finish and verify before starting the next

BAD — verbose, generic, full of things the agent already knows (annotated):

About Me ← REMOVE: not actionable

I am a senior software engineer who values ← REMOVE: narrative, not instruction clean code and best practices. ← REMOVE: generic, no one disagrees

Code Style

• Use meaningful variable names ← REMOVE: generic best practice
• Write clean, maintainable code ← REMOVE: generic, adds nothing
• Use async/await for asynchronous operations ← REMOVE: agent already knows
• Handle errors with try/catch ← REMOVE: agent already knows
• Import modules at the top of the file ← REMOVE: agent already knows
• Files: kebab-case ← KEEP: naming convention
• Variables: camelCase ← MERGE: combine with above
• Components: PascalCase ← MERGE: combine with above

Project Structure ← REMOVE: entire section

src/ ← REMOVE: agent runs ls ├── components/ ← REMOVE: agent runs ls ├── utils/ ← REMOVE: agent runs ls └── lib/ ← REMOVE: agent runs ls

Tools

• Package manager: pnpm ← KEEP: preference
• Always run npm install before starting ← REMOVE: contradicts pnpm above
• Use prettier for formatting ← REMOVE: agent reads config