claude-md

A lightweight global CLAUDE.md for Claude Code, merging code-quality principles with session workflow discipline.

What's inside

• Task sizing — classify every task before touching code: small tasks get fixed autonomously with no ceremony, big tasks (multi-file, architectural) go through plan mode and wait for confirmation.
• Think before coding — state assumptions explicitly, ask about ambiguous requirements (never about clear bugs), and admit uncertainty instead of guessing confidently.
• Simplicity first — minimum code that solves the actual problem; no speculative abstractions, no unrequested config options, new dependencies need justification.
• Surgical changes — touch only what the task requires; no drive-by refactors, renames, or formatting churn in unrelated code.
• Verify before done — never claim something works without running it; for bugs, reproduce first, fix, then confirm the reproduction no longer fails.
• Autonomy rules — fix clear bugs without asking, use subagents to keep the main context clean, stop and report after two failed fix attempts instead of thrashing.
• Stack conventions — sensible defaults for Next.js/TypeScript, Python, and Swift/macOS, plus security defaults and communication style.

Install

Option A: Global (recommended)

Installs as your user-level CLAUDE.md, applied to every project on your machine:

mkdir -p ~/.claude && curl -o ~/.claude/CLAUDE.md https://raw.githubusercontent.com/currylaksa/claude-md/main/CLAUDE.md

Note: back up any existing ~/.claude/CLAUDE.md first — this overwrites it.

Option B: Per-project

New project:

curl -o CLAUDE.md https://raw.githubusercontent.com/currylaksa/claude-md/main/CLAUDE.md

Existing project (append to your current CLAUDE.md):

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/currylaksa/claude-md/main/CLAUDE.md >> CLAUDE.md

Whichever option you pick, edit the Stack Conventions section to match your own languages.

Customize

Universal principles belong in the global file; project-specific rules belong in each repo's own ./CLAUDE.md. Keep it under 200 lines, and delete any line that doesn't actually change behavior — every line spends context on every request, so it has to earn its place.

Credits & Thanks

Sincere thanks to:

• Andrej Karpathy, whose observations on LLM coding pitfalls inspired the core principles here, as distilled by multica-ai in andrej-karpathy-skills.
• Boris Cherny (creator of Claude Code), whose personal CLAUDE.md shaped the workflow sections.

License

MIT