Think about what happens when a new developer joins your team. There’s a knowledge transfer session — someone walks them through the architecture, the coding conventions, the “we tried X but it didn’t work” stories. They spend weeks absorbing tribal knowledge that lives in people’s heads and Slack threads.

Now think about what happens when you start a new Claude Code session. It reads your CLAUDE.md, loads your hooks, discovers your skills, checks its memory. In seconds, it has context that took the new developer weeks to build. The interesting part isn’t that Claude Code can do this — it’s that the infrastructure you build for Claude Code is the exact same infrastructure your team needs for onboarding.

The Mapping

Much of what I’ll describe here was inspired by a fantastic Reddit post by u/JokeGold5455 [1] — a software engineer who solo-rewrote a ~100K LOC internal tool into ~300K LOC over 6 months using Claude Code on the $200/month Max plan. They extracted their patterns into an open-source showcase repo [2] that’s one of the best references I’ve found for production Claude Code usage. I’ll build on their patterns and connect them to the official Claude Code documentation [3].

This post is about treating Claude Code not just as a coding assistant, but as a forcing function for documenting and enforcing your team’s knowledge.

Team Need Traditional Approach Claude Code Feature
Coding conventions Wiki page (often stale) CLAUDE.md
Code review standards Reviewer memory Hooks (pre/post tool)
Common workflows Tribal knowledge Skills (slash commands)
Architecture context Onboarding doc (outdated by week 2) Memory + Rules
“Don’t do X” guardrails PR review comments PreToolUse hooks

CLAUDE.md — Your Coding Conventions, Version-Controlled

CLAUDE.md [4] is a markdown file that Claude reads at the start of every session. Put it in your repo root, and it becomes your project’s instruction manual. The key insight is the layering system:

Scope Location Who writes it Shared?
Project ./CLAUDE.md Team (committed to repo) Yes
Rules .claude/rules/*.md Team (committed to repo) Yes
Local ./CLAUDE.local.md Individual (gitignored) No
User ~/.claude/CLAUDE.md Individual No

The project CLAUDE.md is your team’s coding conventions — committed, version-controlled, reviewed in PRs just like code. When someone updates the convention, everyone (including Claude) gets it in the next pull. Rules files let you split by topic: code-style.md, testing.md, security.md. Path-specific rules mean your API team’s conventions only load when Claude is working on API files:

# .claude/rules/api-conventions.md
---
paths:
  - "src/api/**/*.ts"
---

All API endpoints must:
- Validate input with Zod schemas
- Return standard error format { error: string, code: number }
- Include request ID in response headers

CLAUDE.local.md is for personal preferences that don’t belong in the shared repo. The layering means team standards and personal preferences coexist without conflicts.

Keep CLAUDE.md under 200 lines. It loads into every session, and bloated instructions reduce adherence. Move detailed content into .claude/rules/ files [5] — they load on demand based on what files Claude is working with.

Hooks — Deterministic Enforcement, Not Suggestions

Hooks [6] are shell commands that execute at specific points in Claude’s workflow — deterministic automation, not suggestions. You’re not asking Claude to remember to run the linter, you’re guaranteeing it runs.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$(cat /dev/stdin | jq -r '.tool_input.file_path')\""
          }
        ]
      }
    ]
  }
}

The hook types map to different team needs:

Hook Event When it fires Team use case
PreToolUse Before a tool runs Block unsafe operations, enforce tool preferences
PostToolUse After a tool succeeds Auto-format, lint, log changes
UserPromptSubmit When you send a prompt Inject context, activate relevant skills
Stop When Claude finishes responding Run tests, check types, verify builds

The UserPromptSubmit hook is particularly clever [2]. It reads your prompt, matches it against keyword/regex patterns, and injects relevant skill suggestions before Claude processes the prompt. This solves the problem that skills don’t auto-activate reliably — the hook makes activation deterministic.

One important caveat from u/JokeGold5455’s experience [1]: be careful with PostToolUse hooks that modify files. Each file modification triggers a system reminder with the diff, which consumes context tokens. A Prettier hook that runs on every edit can eat 160K tokens in just a few rounds. Use Stop hooks for non-blocking checks instead.

Hooks receive JSON on stdin and communicate back through exit codes: 0 means proceed, 2 means block. This lets you build guardrails:

#!/usr/bin/env python3
# .claude/hooks/check-env-files.py
import sys, json

event = json.load(sys.stdin)
file_path = event.get("tool_input", {}).get("file_path", "")

if ".env" in file_path and not file_path.endswith(".env.example"):
    print("Blocked: do not edit .env files directly.", file=sys.stderr)
    sys.exit(2)

Skills — Your Team’s Playbooks

Skills [7] are markdown files that extend Claude’s capabilities with custom slash commands. Think of them as your team’s playbooks — documented procedures that Claude follows step by step.

# .claude/skills/deploy/SKILL.md
---
name: deploy
description: Deploy to staging or production environment
disable-model-invocation: true
---

Deploy to $1 environment:

1. Run the test suite: `npm test`
2. Build the project: `npm run build`
3. Check for uncommitted changes
4. If deploying to production, require explicit confirmation
5. Run: `./scripts/deploy.sh $1`
6. Verify health check at the deployed URL

The recommended pattern [2] keeps each skill under 500 lines with progressive disclosure:

.claude/skills/
  backend-dev/
    SKILL.md              # Overview + navigation (<500 lines)
    resources/
      api-patterns.md     # Deep dive on API patterns
      db-migrations.md    # Database migration guide
      error-handling.md   # Error handling conventions

Claude loads the main SKILL.md first, then pulls resource files only when needed. This improved token efficiency 40-60% compared to monolithic skill files.

Key configuration options:

Option Purpose Example
disable-model-invocation: true Only you can trigger (deploys, commits) Prevents accidental deploys
user-invocable: false Only Claude can trigger Background knowledge
context: fork Runs in isolated subagent context Heavy tasks that won’t bloat main context
paths: ["src/**/*.ts"] Only loads for matching files Language-specific conventions

Skills can inject dynamic context using shell commands:

---
name: pr-review
description: Review current pull request
---

## PR Context
- Diff: !`gh pr diff`
- Files changed: !`gh pr diff --name-only`

Review this PR for: code style, test coverage, security issues.

Memory — What Claude Tells Itself

The memory system [4] is Claude’s own notes — things it learns during conversations and persists for future sessions. It’s stored in ~/.claude/projects/<project>/memory/ and automatically loaded at session start.

This is different from CLAUDE.md:

What Where to put it Why
“Always use 2-space indent” CLAUDE.md Team convention, you define it
“This project uses direnv, run direnv allow” Memory Claude learned it, reminds itself
“User prefers terse responses” Memory Personal preference, not a project rule
“API routes live in src/api/handlers/” CLAUDE.md or rules/ Project structure, should be explicit

The Documentation Lifecycle — Why This Actually Works

The traditional problem with team documentation is that it goes stale. Someone writes an architecture doc, it’s accurate for a month, then the code drifts and nobody updates the doc. This is why tribal knowledge exists — the real conventions live in people’s heads because the written docs can’t be trusted.

Claude Code changes this dynamic because the documentation isn’t just for humans — it’s for your coding assistant too. When CLAUDE.md is wrong, Claude does the wrong thing. When a hook is misconfigured, builds break. When a skill is outdated, workflows fail. The documentation has an immediate feedback loop with code production, which means it actually gets maintained.

The dev-docs pattern from u/JokeGold5455 [1] makes this explicit. For every large task, create three files:

dev/active/feature-name/
  plan.md      # Strategic plan — what we're building and why
  context.md   # Key files, decisions, dependencies
  tasks.md     # Checklist of remaining work

These survive context resets and session boundaries. When you hit 15% remaining context, update the dev docs, compact, and say “continue” — Claude picks up where it left off.

graph LR
    CLAUDE["CLAUDE.md\n(conventions)"] --> SESSION["Claude Session"]
    HOOKS["Hooks\n(enforcement)"] --> SESSION
    SKILLS["Skills\n(playbooks)"] --> SESSION
    MEMORY["Memory\n(learnings)"] --> SESSION
    DEVDOCS["Dev Docs\n(active context)"] --> SESSION

    SESSION --> CODE["Code Changes"]
    SESSION --> UPDATE["Update Docs"]
    UPDATE --> CLAUDE
    UPDATE --> SKILLS
    UPDATE --> DEVDOCS

    style CLAUDE fill:#264653,stroke:#264653,color:#fff
    style HOOKS fill:#e76f51,stroke:#e76f51,color:#fff
    style SKILLS fill:#2a9d8f,stroke:#2a9d8f,color:#fff
    style MEMORY fill:#e9c46a,stroke:#e9c46a,color:#000
    style DEVDOCS fill:#f4a261,stroke:#f4a261,color:#000
    style SESSION fill:#40916c,stroke:#40916c,color:#fff
    style CODE fill:#2d6a4f,stroke:#2d6a4f,color:#fff
    style UPDATE fill:#2d6a4f,stroke:#2d6a4f,color:#fff

Practical Setup Guide

Step 1: Start with CLAUDE.md. Document your build commands, test commands, coding conventions. Keep it under 200 lines. Commit it. This alone is worth doing even if you never use Claude Code — it’s the onboarding doc your team already needs.

Step 2: Add rules for specifics. Split into .claude/rules/ by topic. Use path-specific rules for different parts of the codebase.

Step 3: Add hooks for enforcement. Start with Stop hooks for formatting and type checking. Add PreToolUse guardrails for things that should never happen — editing .env files, running destructive commands.

Step 4: Build skills for repeating workflows. Deploy procedures, PR review checklists, debugging runbooks.

Step 5: Let memory accumulate naturally. Don’t pre-populate it. Let Claude learn your project’s quirks over time.

The diet103/claude-code-infrastructure-showcase [2] repo is an excellent reference — a real-world extraction from 6 months of production use on a ~300K LOC TypeScript project. The author (u/JokeGold5455 on Reddit) spent $1,200 total over 6 months on the Max plan and shared their complete methodology [1].

The Meta-Insight

The infrastructure you build to make Claude Code effective is the same infrastructure that makes your team effective. CLAUDE.md is your coding standards doc. Hooks are your CI checks running locally. Skills are your team’s runbooks. Memory is institutional knowledge.

If you keep these up to date — and you will, because Claude breaks when they’re wrong — you’ve solved the documentation problem not by trying harder to write docs, but by making documentation a load-bearing part of your development workflow. The new developer who joins your team doesn’t just get a stale wiki page. They get a working system that actively guides their coding assistant toward the team’s conventions.

The coding assistant isn’t just a tool. It’s a forcing function for the practices you already know you should have.

How are you structuring your Claude Code setup for team workflows?

References:

[1] u/JokeGold5455. “Claude Code is a Beast — Tips from 6 Months of Hardcore Use.” r/ClaudeCode 2025.
[2] diet103. “claude-code-infrastructure-showcase.” GitHub.
[3] “Claude Code Overview.” Anthropic.
[4] “Claude Code — Memory, CLAUDE.md, and .claude/rules.” Anthropic.
[5] “Organize Instructions with .claude/rules.” Anthropic.
[6] “Claude Code — Hooks.” Anthropic.
[7] “Claude Code — Skills.” Anthropic.
[8] “Claude Code — Sub-agents.” Anthropic.
[9] “Claude Code — Settings.” Anthropic.
[10] “Claude Code — Context Window Management.” Anthropic.
[11] “Claude Code — Best Practices.” Anthropic.