Ship Standards, Not Wikis: The Foundation

February 6, 2026

This is Part 1 of a four-part series on onboarding engineering teams with Claude Code. Part 2: Plugins and the Marketplace · Part 3: Skills · Part 4: Hooks and Putting It All Together GitHub template →

The Onboarding Problem

Every engineering organization has a version of the same story. A new developer joins. They're handed a Confluence link, a Notion page, or a README that was last updated eighteen months ago. They spend their first week asking questions in Slack that the wiki was supposed to answer. By the time they're productive, they've absorbed the team's real standards through osmosis—watching pull requests, getting review comments, and learning which linter rules people actually care about.

The standards exist. They're just trapped in people's heads instead of in the toolchain.

Claude Code changes this equation. Instead of documenting your team's coding standards, rituals, and workflows in a wiki that drifts out of sync with reality, you encode them directly into the development environment. New engineers don't read about your conventions—they work inside them from their first commit.

The Three Pillars

Claude Code's extensibility model rests on three mechanisms that layer on top of each other:

CLAUDE.md is a markdown file committed to your repository that Claude reads automatically at the start of every session. It's your team's constitution—the baseline context for every interaction.

Skills are instruction sets—also committed to your repo—that teach Claude your team's specific workflows, commands, and rituals. They're how you encode tribal knowledge.

Hooks are lifecycle triggers that execute shell commands or agent-based validations at specific points during a session. They're how you enforce standards automatically.

Each addresses a different layer of the onboarding problem. CLAUDE.md sets the context. Skills transfer the knowledge. Hooks enforce the rules. Together, they replace the onboarding wiki with something that actually works.

The following articles in this series cover each layer in depth. This one starts with the foundation.

CLAUDE.md: The Living Standards Doc

CLAUDE.md is a markdown file at the root of your repository that Claude reads automatically at the beginning of every session. Think of it as your team's constitution—the document that establishes the baseline context for every interaction.

What this means in practice: A new developer clones the repo and opens Claude Code. Without being asked, Claude already knows your tech stack, your naming conventions, and your testing requirements. The developer doesn't read a setup guide—they just start working, and the right patterns are applied automatically.

Here's a typical example of what a team's CLAUDE.md looks like:

# CLAUDE.md

## Tech Stack
- Next.js 14 with App Router
- TypeScript strict mode
- Tailwind CSS, no custom CSS files
- Prisma ORM with PostgreSQL

## Code Standards
- All new functions must have JSDoc comments
- Use named exports, never default exports
- Error boundaries around every route segment
- No console.log in production code—use the logger util

## Testing
- Unit tests with Vitest, co-located with source files
- Integration tests in __tests__/integration/
- Minimum 80% branch coverage on new code

## Git Conventions
- Conventional commits: feat|fix|chore|docs(scope): message
- Squash merge to main
- Branch naming: team/ticket-slug

This file is committed to version control, reviewed in PRs like any other code, and applies to every developer on the team. When someone changes the testing framework or adopts a new naming convention, the CLAUDE.md is updated in the same PR. The standards and the code evolve together.

Monorepos

For monorepos, CLAUDE.md files cascade. A root-level file establishes shared conventions, while subdirectory files (packages/api/CLAUDE.md, packages/web/CLAUDE.md) add context specific to each package. Claude loads whichever files are relevant to the directory it's operating in.

Personal Overrides

Developers can also maintain a CLAUDE.local.md for personal preferences—editor quirks, preferred explanation styles, aliases—that stay gitignored and never pollute the shared standards.

Why It Works

The difference between a CLAUDE.md and a wiki entry is that CLAUDE.md is read at the moment the developer is doing the work, not during onboarding week when it's too abstract to stick. The developer asking Claude to create a new component gets the naming convention applied automatically. They don't have to remember it.

A well-written CLAUDE.md answers the questions that new developers ask in Slack. It describes the tech stack, the patterns that aren't obvious from the code, the rules that exist for historical reasons, and the things that would get flagged in a code review. It's a living document: when you add a review comment to a PR, consider whether that comment should be in CLAUDE.md instead.

Continue reading: