Karpathy's CLAUDE.md solves the problem of 1 engineer managing 1 agent, but engineering teams need 4 additional mechanisms (onboarding, version control, enforcement, and conflict resolution) to turn a personal discipline file into a team standard.
Suitable tasks:
Understand how CLAUDE.md scales from an individual to a team
Design a CLAUDE.md standard for an engineering team
Resolve drift caused by multiple engineers using different CLAUDE.md files
Handle configuration conflicts in a shared codebase
Unsuitable tasks:
Simple projects for individual developers (use Karpathy's version directly)
Scenarios that do not require team collaboration
Applicable model version: Claude Opus 4.7
Applicable client, Agent, or API: Claude Code CLI
Recommended reasoning levels and parameters: N/A (methodology guidance; no specific parameters involved)
On January 26, 2026, Karpathy posted on X about his frustration with AI coding agents. The next day, developer Forrest Chang encoded those frustrations into a 65-line CLAUDE.md file and pushed it to GitHub (multica-ai/andrej-karpathy-skills). The file became a behavioral standard for Claude Code.
Karpathy named 3 failure modes:
Coding agents make incorrect assumptions and execute without checking
Overcomplicate code, bloating abstractions and shipping a 1,000-line implementation when 100 lines would be enough
Change or delete code they do not fully understand, even when it is unrelated to the task
Chang's file turned each frustration into a named principle:
Think Before Coding: State assumptions explicitly, stop when confused, and do not guess
Simplicity First: Write the smallest code that solves the stated problem; do not add unrequested abstractions
Surgical Changes: Do not touch code unrelated to the request, even when adjacent code appears improvable
Goal-Driven Execution: Convert an ambiguous task into verifiable success criteria before starting
Workflow reversal:
November 2025: 80% manual coding, 20% through agents
End of January 2026: 20% review and polishing, 80% produced by agents
The reversal was completed within 8 weeks
Three engineers, one codebase. Six weeks ago, each copied CLAUDE.md. Each modified it for their own preferences.
Engineer A relaxed Surgical Changes because she was working on a large-scale migration
Engineer B tightened Goal-Driven Execution because his team had been hurt by agents shipping untested functionality
Engineer C never modified the file, but did not know the others had
The files now say different things. Agents behave differently for each engineer. No one knows. There is no mechanism for detecting drift.
The consequences surface during code review: a reviewer notices that Engineer A's latest PR touched more files than her ticket suggested, but cannot trace the reason.
Engineer A's CLAUDE.md tells the agent that it may clean up orphaned imports as part of a task. Engineer A's task touches a utility in services/shared/auth.py. Engineer B's service depends on that utility, and Engineer B's agent operates under a different CLAUDE.md and builds around the existing import structure.
One engineer's "clean up your own mess" becomes another engineer's Monday-morning integration test failure.
The agents do exactly what their files tell them to do. The files tell them different things. Shared code pays the price.
A new engineer joins on Tuesday. They get repository access on Wednesday. They copy CLAUDE.md on Thursday. No one explains what the team's specific additions to the file mean, why the file differs from the public Karpathy version, or what to do when an agent does something the file does not cover.
The standard exists. The transmission of the standard does not.
PR #54 in the public repository proposes advisory hooks for all 4 principles. The PR's own design philosophy section describes the hooks as advisory: they emit exit warnings on stderr without blocking, and fail open when they receive malformed input.
Pure instructions in a pure Markdown file are suggestions. Suggestions are not standards.
The repository's most active contributors are building around the limitations. The written principles fail at the moment they matter most to an engineering organization: when agents run at scale without supervision.
Problem: New engineers do not know what the team's specific additions to the file mean.
Solution:
Create team-specific CLAUDE.md onboarding documentation
Explain the team's interpretation of each principle
Provide an escalation path for when an agent does something the file does not cover
Problem: Each engineer modifies their own copy, causing drift.
Solution:
Store CLAUDE.md in version control as a team standard
Use pull requests for changes
Provide an override mechanism for personal preferences (such as .claude.local.md)
Problem: Pure instructions are suggestions, not standards.
Solution:
Implement enforcement hooks (not merely advisory ones)
Validate compliance in CI/CD
Provide fail-safe mechanisms for unattended situations
Problem: There is no resolution mechanism when different engineers' CLAUDE.md files conflict.
Solution:
Define the authoritative source for shared code
Create a team-level CLAUDE.md for shared services
Establish a conflict-resolution process
Three-layer structure:
Core principles (immutable):
Start with Karpathy's 4 principles
Change them through pull requests
All engineers must follow them
Team-specific (controlled variability):
The team's interpretation of the principles
Change them through pull requests
All engineers on the team must follow them
Personal preferences (local overrides):
Stored in .claude.local.md
Not committed to version control
Cannot override core or team-specific principles
Enforcement mechanisms:
Use hooks to validate compliance
Check in CI/CD
Provide fail-safe behavior for unattended situations
Conflict resolution:
An authoritative source for shared code
A team-level CLAUDE.md for shared services
A clear escalation path
Assess the current state:
Check each engineer's CLAUDE.md on the team
Identify drift and conflicts
Establish the three-layer structure:
Create the core principles (starting with Karpathy's 4 principles)
Create team-specific principles
Provide an override mechanism for personal preferences
Implement version control:
Store CLAUDE.md in version control
Use pull requests for changes
Use .claude.local.md for personal overrides
Implement enforcement:
Use hooks to validate compliance
Check in CI/CD
Provide fail-safe behavior for unattended situations
Establish an onboarding process:
Create team-specific onboarding documentation
Explain the team's interpretation of each principle
Provide an escalation path
Establish conflict resolution:
Define the authoritative source for shared code
Create a team-level CLAUDE.md for shared services
Establish a conflict-resolution process
Review regularly:
Review CLAUDE.md changes monthly
Identify and resolve drift
Update the onboarding documentation
Karpathy's CLAUDE.md has approximately 184k stars and 97 open pull requests on GitHub (as of June 28, 2026)
The file was not actually written by Karpathy; it was encoded by Forrest Chang on January 27, 2026
Karpathy's workflow reversed from 80% manual coding to 80% agent production within 8 weeks
The public repository has 138 pull requests, of which 97 are open
The core principles have not changed since January 27, despite 5 months of community expansion proposals
This analysis targets engineering teams and does not apply to individual developers
The three-layer structure must be adapted to the team's size and needs
Enforcement hooks may require additional development and testing
The conflict-resolution process must be tailored to the team's culture
The article's core point: "The file was designed for 1 engineer managing 1 agent in 1 repo. It is excellent at that. Engineering organizations are a different problem."
"Many developers copied the file into their repo and moved on. That is a personal productivity move. It is not a team standard, and the difference matters more than the star count suggests."
Claude Opus 4.7
