Quick Answer: Anthropic teams maintain a shared CLAUDE.md file checked into git that documents AI mistakes and best practices. Whenever Claude does something wrong, they add it to the file so it doesn't repeat the error. Boris Cherny's team's CLAUDE.md is 2.5k tokens and gets updated multiple times weekly. This "institutional memory" means the entire team benefits from every lesson learned.
Every developer has experienced this: you correct an AI's mistake, only to see it make the same mistake again in a different context. Boris Cherny's team at Anthropic solved this with a deceptively simple practice.
"Anytime we see Claude do something incorrectly we add it to the CLAUDE.md, so Claude knows not to do it next time." — Boris Cherny
Here's how CLAUDE.md works and how to implement this powerful practice in your own team.
Watch: Setting Up CLAUDE.md for Your Project
Peter Yang demonstrates initializing CLAUDE.md at the 10:44 mark—the same technique Boris Cherny's team uses for persistent project memory.
What is CLAUDE.md?
CLAUDE.md is a markdown file that lives in your repository, containing instructions, preferences, and learnings for Claude. When Claude Code starts a session, it reads this file and incorporates the guidance into its behavior.
Think of it as institutional memory for AI—a way to encode everything your team has learned about working effectively with Claude.
The Structure
A typical CLAUDE.md includes:
# Project: [Your Project Name]
## Code Style
- Use TypeScript strict mode
- Prefer functional components in React
- Use named exports, not default exports
## Common Mistakes to Avoid
- Don't use deprecated API methods (list specific ones)
- Always handle loading and error states
- Never commit console.log statements
## Project-Specific Patterns
- Authentication uses [specific pattern]
- Database queries should use [specific ORM]
- API responses follow [specific format]
## PR Guidelines
- Include tests for new features
- Update documentation for API changes
- Follow conventional commit format
Why It Works
Claude reads CLAUDE.md at the start of each session. The instructions become part of its context, shaping every response. Mistakes documented once are avoided forever—across all team members, all sessions.
Why Git-Based is Important
"Their team shares a single CLAUDE.md for the Claude Code repo. They check it into git, and the whole team contributes multiple times a week."
Checking CLAUDE.md into git provides crucial benefits:
1. Version Control
Like any code, the file has history:
- Who added what guidance
- When changes were made
- Why certain rules exist (in commit messages)
You can trace the evolution of your AI collaboration practices.
2. Code Review
Changes to CLAUDE.md can be reviewed:
- Team members validate new rules
- Catch overly specific or incorrect guidance
- Ensure consistency with project direction
3. Shared Across Team
Everyone uses the same CLAUDE.md:
- Consistent AI behavior across all developers
- New team members get established practices automatically
- No individual drift in AI collaboration style
4. Branch-Specific Guidance
Different branches can have different CLAUDE.md content:
- Feature branches: Specific guidance for that feature
- Main branch: Stable, tested guidance
- Experimental: Trying new approaches
The @.claude Tag Workflow
Cherny's team has a sophisticated workflow for learning from code reviews:
"He often uses the @.claude tag on coworkers's PRs to add learnings to CLAUDE.md, ensuring knowledge from each PR is preserved."
How It Works
- During PR review, spot an AI-generated issue
- Add
@.claudecomment with the learning - Automated system adds to CLAUDE.md
- Future sessions avoid that mistake
Example Flow
PR #1234: Add user notification feature
Reviewer comment:
@.claude When implementing notifications, always include:
- User preference check (can opt out)
- Rate limiting (max 10 per hour)
- Fallback for failed delivery
This gets added to CLAUDE.md, preventing future notification
implementations from missing these requirements.
GitHub Action Integration
The @.claude system can be automated with GitHub Actions:
name: Update CLAUDE.md from PR comments
on:
pull_request_review_comment:
types: [created]
jobs:
update-claude-md:
if: contains(github.event.comment.body, '@.claude')
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Extract and append to CLAUDE.md
run: |
# Parse @.claude comment and append to CLAUDE.md
# Create PR with update
This automation ensures every learning is captured without manual file editing.
Building Your Own CLAUDE.md
Here's a comprehensive guide to creating an effective CLAUDE.md:
Step 1: Start with Basics
Begin with fundamental project information:
# CLAUDE.md
## Project Overview
[Brief description of what this project does]
## Tech Stack
- Frontend: React 18, TypeScript, Tailwind CSS
- Backend: Node.js, Express, PostgreSQL
- Testing: Jest, React Testing Library
## Development Setup
- Run `npm install` to install dependencies
- Run `npm run dev` for development server
- Run `npm test` for tests
Step 2: Document Code Style
Encode your team's conventions:
## Code Style
### General
- Use TypeScript strict mode
- Prefer `const` over `let`
- Use early returns for guard clauses
### React
- Use functional components with hooks
- Prefer named exports
- Colocate tests with components
### API
- Use REST conventions
- Return consistent error format
- Include pagination for list endpoints
Step 3: List Common Mistakes
This is the most valuable section—document actual mistakes:
## Common Mistakes to Avoid
### Authentication
- DON'T store tokens in localStorage (use httpOnly cookies)
- DON'T expose user IDs in URLs (use UUIDs)
### Database
- DON'T use raw SQL queries (use parameterized queries)
- DON'T skip migrations (always create migration files)
### React
- DON'T mutate state directly
- DON'T use array index as key for dynamic lists
### Testing
- DON'T mock everything (prefer integration tests)
- DON'T skip error case testing
Step 4: Document Project Patterns
Include project-specific patterns:
## Project Patterns
### Error Handling
All errors should use the AppError class:
\`\`\`typescript
throw new AppError('User not found', 404, 'USER_NOT_FOUND');
\`\`\`
### API Responses
All API responses follow this format:
\`\`\`json
{
"success": true,
"data": {...},
"meta": { "pagination": {...} }
}
\`\`\`
### Component Structure
Components follow this structure:
\`\`\`
components/
ComponentName/
ComponentName.tsx
ComponentName.test.tsx
ComponentName.styles.ts
index.ts
\`\`\`
Step 5: Add PR Guidelines
Help Claude create better PRs:
## PR Guidelines
### Commit Messages
Follow conventional commits:
- feat: New feature
- fix: Bug fix
- docs: Documentation
- test: Tests
- refactor: Code refactoring
### PR Description
Include:
- Summary of changes
- Testing performed
- Screenshots for UI changes
### Review Checklist
Before submitting:
- [ ] Tests pass
- [ ] No console errors
- [ ] TypeScript compiles
- [ ] Documentation updated
Team Collaboration on CLAUDE.md
Establishing Contribution Norms
For CLAUDE.md to work, the team needs shared norms:
When to Add:
- After encountering a repeatable mistake
- When establishing a new pattern
- After a post-mortem identifies an issue
- When a new team member asks "why do we do X?"
When NOT to Add:
- One-time edge cases
- Personal preferences without team consensus
- Overly specific instructions that don't generalize
Review Process
Treat CLAUDE.md changes like code:
1. Make change in branch
2. Open PR with explanation
3. Team reviews and approves
4. Merge to main
This ensures quality and consensus.
Regular Maintenance
Schedule periodic review:
Monthly:
- Remove outdated guidance
- Consolidate redundant entries
- Check for contradictions
Quarterly:
- Major restructuring if needed
- Validate against current practices
- Gather team feedback
Size and Organization
"Their CLAUDE.md is 2.5k tokens."
Cherny's team keeps CLAUDE.md at 2.5k tokens—substantial but not overwhelming. This size:
- Fits comfortably in context
- Covers major concerns
- Doesn't overwhelm with minutiae
Organization for Larger Files
If your CLAUDE.md grows large, organize hierarchically:
# CLAUDE.md
## Quick Reference (most important)
[Critical rules that affect every task]
## Code Style
[Detailed style guidance]
## Architecture
[System design patterns]
## Common Mistakes
[Documented errors to avoid]
## PR Process
[Pull request guidelines]
## Team Conventions
[Non-code conventions]
Front-load the most important information.
Splitting for Large Projects
For very large projects, consider splitting:
.claude/
CLAUDE.md # General project guidance
frontend.md # Frontend-specific
backend.md # Backend-specific
testing.md # Testing conventions
Claude can be directed to relevant files as needed.
Sample CLAUDE.md Template
Here's a complete template to start with:
# CLAUDE.md - [Project Name]
## Project Overview
[2-3 sentences describing the project]
## Quick Reference
- [Most important rule 1]
- [Most important rule 2]
- [Most important rule 3]
## Tech Stack
- **Frontend:** [technologies]
- **Backend:** [technologies]
- **Database:** [technologies]
- **Testing:** [technologies]
## Code Style
### General Principles
- [Principle 1]
- [Principle 2]
### Language-Specific
- [Rule 1]
- [Rule 2]
## Common Mistakes to Avoid
### Critical (Will Break Things)
- [Mistake 1]: [Why it's bad] → [What to do instead]
- [Mistake 2]: [Why it's bad] → [What to do instead]
### Important (Will Cause Issues)
- [Mistake 1]: [Correct approach]
- [Mistake 2]: [Correct approach]
## Project Patterns
### [Pattern Name 1]
[Description and example]
### [Pattern Name 2]
[Description and example]
## PR Guidelines
### Commit Message Format
[Format specification]
### Required Before Merge
- [ ] Tests pass
- [ ] Code review approved
- [ ] Documentation updated
## Team Conventions
- [Convention 1]
- [Convention 2]
---
Last updated: [Date]
Contributors: [Team members]
Measuring CLAUDE.md Effectiveness
How do you know if CLAUDE.md is working?
Metrics to Track
Repeat Errors: Before CLAUDE.md: How often did you correct the same mistakes? After CLAUDE.md: Has this frequency decreased?
Onboarding Speed: How quickly do new team members achieve productive AI collaboration?
PR Quality: Are AI-generated PRs passing review more often on first attempt?
Qualitative Feedback
Ask the team:
- "Is Claude following our conventions?"
- "Are you still correcting the same things repeatedly?"
- "What should we add to CLAUDE.md?"
Frequently Asked Questions
How specific should CLAUDE.md be?
Specific enough to prevent real mistakes, general enough to apply across contexts. "Don't use any" is too vague. "Use React Query for all data fetching" is appropriately specific.
What if team members disagree on a rule?
Discuss and reach consensus before adding. CLAUDE.md should reflect team decisions, not individual preferences.
How often should we update it?
Cherny's team updates "multiple times weekly." Update when you encounter a new mistake or pattern worth documenting.
Does CLAUDE.md work with other AI tools?
The concept applies to any AI that can read context files. Specific syntax may vary.
Should we have CLAUDE.md for open source projects?
Yes! It helps contributors get consistent AI assistance immediately.
Bottom Line
CLAUDE.md is a simple but powerful practice: document AI mistakes and best practices in a shared file. The benefits compound:
Key takeaways:
- Check CLAUDE.md into git for version control and sharing
- Document actual mistakes as they occur
- Use @.claude tags to capture learnings from PRs
- Keep it organized and maintainable (~2.5k tokens)
- Review and update regularly
The result is institutional memory for AI collaboration—every lesson learned benefits every team member, automatically.
Want to implement effective AI collaboration practices in your team? Contact Houston IT Developers to learn how we help organizations build productive AI-assisted development workflows.
Sources:
Houston IT Developers
Houston IT Developers is a leading software development and digital marketing agency based in Houston, Texas. We specialize in web development, mobile apps, and digital solutions.
View all posts →Need Help With Your Project?
Our team of experts is ready to help you build your next web or mobile application. Get a free consultation today.
Get in Touch
