Claude Working Agreement

A shareable, user-level CLAUDE.md — a global working agreement for Claude Code that encodes four complementary frameworks into one contract.

What's inside

CLAUDE.md combines:

• Karpathy Guidelines — behavioral rules to avoid common LLM coding mistakes (think before coding, simplicity first, surgical changes, goal-driven execution).
• Grill Workflow — stress-test a plan before building it, gated so it fires only when it's worth it.
• Documentation Conventions — CONTEXT.md (glossary) and docs/adr/ (Architecture Decision Records), with consent gating so no files get created unprompted.
• DOX Hierarchy — how to read and maintain AGENTS.md contracts across a repo.

How to use it

Drop CLAUDE.md into one of:

• ~/.claude/CLAUDE.md — applies globally to every project on your machine (recommended).
• A project root — applies to that repo only.

Claude Code loads it automatically at session start.

Companion skills

The grill workflow pairs with two Claude Code skills (grill-me, grill-with-docs). This repo holds the agreement itself; the skills are installed separately under ~/.claude/skills/.

Sources

• Karpathy Guidelines — https://github.com/multica-ai/andrej-karpathy-skills
• grill-me / grill-with-docs — https://github.com/mattpocock/skills
• DOX — https://github.com/agent0ai/dox

License

MIT