Part 1: The Global CLAUDE.md as Security Gatekeeper

The Memory Hierarchy

Claude Code loads CLAUDE.md files in a specific order:

Level Location Purpose
Enterprise /etc/claude-code/CLAUDE.md Org-wide policies
Global User ~/.claude/CLAUDE.md Your standards for ALL projects
Project ./CLAUDE.md Team-shared project instructions
Project Local ./CLAUDE.local.md Personal project overrides

Your global file applies to every single project you work on.

What Belongs in Global

1. Identity & Authentication

## GitHub Account
**ALWAYS** use **YourUsername** for all projects:
- SSH: `git@github.com:YourUsername/<repo>.git`

## Docker Hub
Already authenticated. Username in `~/.env` as `DOCKER_HUB_USER`

## Deployment
Use Dokploy MCP for production. API URL in `~/.env`

Why global? You use the same accounts everywhere. Define once, inherit everywhere.

2. The Gatekeeper Rules

## NEVER EVER DO

These rules are ABSOLUTE:

### NEVER Publish Sensitive Data
- NEVER publish passwords, API keys, tokens to git/npm/docker
- Before ANY commit: verify no secrets included

### NEVER Commit .env Files
- NEVER commit `.env` to git
- ALWAYS verify `.env` is in `.gitignore`

### NEVER Hardcode Credentials
- ALWAYS use environment variables

Why This Matters: Claude Reads Your .env

Security researchers discovered that Claude Code automatically reads .env files without explicit permission. Backslash Security warns:

"If not restricted, Claude can read .env, AWS credentials, or secrets.json and leak them through 'helpful suggestions.'"

Your global CLAUDE.md creates a behavioral gatekeeper — even if Claude has access, it won't output secrets.

Defense in Depth

Layer What How
1 Behavioral rules Global CLAUDE.md "NEVER" rules
2 Access control Deny list in settings.json
3 Git safety .gitignore

Team Workflows: Evolving CLAUDE.md

Solo developers maintain their own CLAUDE.md. But what about teams? Boris Cherny shares how Anthropic's Claude Code team does it:

"Our team shares a single CLAUDE.md for the Claude Code repo. We check it into git, and the whole team contributes multiple times a week. Anytime we see Claude do something incorrectly we add it to the CLAUDE.md, so Claude knows not to do it next time."

The key insight: CLAUDE.md isn't a static document you write once. It's a living file that evolves with your codebase.

The Pattern: Mistakes Become Documentation

Claude makes mistake → You fix it → You add rule to CLAUDE.md → Claude never makes that mistake again

Example workflow:

  1. Claude uses deprecated API in PR
  2. Reviewer catches it
  3. Team adds to CLAUDE.md: ## API Guidelines\nNEVER use deprecated v1 endpoints. Always use v2.
  4. Future Claude sessions know to avoid v1

@.claude in PR Reviews

Using the Claude Code GitHub Action, you can tag @.claude directly in PR comments:

Reviewer comment on PR #142:
"@.claude add to CLAUDE.md: Always use our internal logger instead of console.log"

Claude updates CLAUDE.md as part of the PR itself. The lesson gets documented where it was learned.

To set this up:

claude /install-github-action

Compounding Engineering

This workflow embodies a concept called Compounding Engineering:

"Each unit of engineering work should make subsequent units easier — not harder."

The traditional approach: fix bug, move on, repeat same mistake later.

The compounding approach: fix bug, document why, never repeat.

Plan → Work → Review → Compound → (better) Plan → ...

The 80/20 inversion: Spend 80% on planning and review, 20% on execution. Each cycle feeds learnings back into the system. Your CLAUDE.md becomes institutional knowledge that compounds over time.

Resources: