Three Layers for Automating Team AI Standards with Claude Code: CLAUDE.md, Custom Commands, and Subagents

After introducing Claude Code to a team, the first problem you run into is this: "Why does my AI refuse to use axios, while my colleague's AI is happily using axios right next to me?" Personal config files are scattered around, team conventions live only in someone's head, and a newly onboarded developer asks the AI and gets back a completely wrong pattern. The end result is a paradox where the more you use AI, the less consistent your team's codebase becomes.

The root cause of this problem is that the AI doesn't know the "team's context." Coding style, architectural decisions, service-specific constraints — all of this exists inside the heads of senior reviewers but never gets communicated to the AI. Many teams eventually give up after having to repeat context like "our team doesn't use axios, business logic goes in the Service layer..." at the start of every single session.

By injecting team standards into the AI via CLAUDE.md, codifying repetitive procedures as custom commands (skills), and delegating parallel work to subagents, your team's collective intelligence becomes internalized as the AI's behavioral baseline. I started out thinking a single CLAUDE.md was enough — "that should do it" — but it wasn't until I understood the combination of custom commands and subagents that team members stopped reverting entire chunks of AI-generated code.

Core Concepts

CLAUDE.md — The Team Constitution for AI

CLAUDE.md is a markdown file that Claude Code automatically reads when a session starts. It lives in two places:

• Home directory (~/.claude/CLAUDE.md): personal settings applied across all projects
• Project root (./CLAUDE.md): team-shared settings applied only to that repo

When both files exist, the project root's CLAUDE.md is layered on top of the home settings. To share team standards, create a CLAUDE.md in the project root and commit it to Git. From the moment a new hire clones the repo, the AI behaves as if it already knows the team's conventions.

# Project Rules
 
## Forbidden Patterns
- No axios → use fetch API or ky instead
- No TypeScript `any` type
- No direct DOM manipulation → handle via React state
 
## Build & Validation Commands
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`
 
## Architecture Rules
- Domain boundaries: frontend(Next.js) / backend(NestJS) / infra(Terraform) — keep separate
- Business logic belongs in Service; keep Controllers thin
- Server Components by default; minimize Client Components
 
## Code Style
- TypeScript strict mode required
- Use async/await (no `.then()`)
- 2-space indentation

💡 Tip: Placement of instructions matters. In practice, LLMs tend to follow content placed at the beginning and end of a file more reliably. As the number of instructions grows, overall compliance also drops, so put the most important forbidden patterns at the top and keep the file under 300 lines.

Based on public examples from teams at GitHub and elsewhere, teams that manage CLAUDE.md well run a feedback loop: whenever the AI generates a wrong pattern, they immediately add it to CLAUDE.md to prevent recurrence. It stops being "the AI made something weird again" and becomes "time to update CLAUDE.md." Run this loop for a few weeks and the file evolves into a living technical document for the team.

Custom Commands (Skills) — Codifying Procedural Knowledge

If CLAUDE.md holds "what's right and wrong (facts)," custom commands (skills) hold "how to do it (procedures)." They are reusable procedures defined as SKILL.md files in the .claude/skills/ directory.

.claude/skills/
├── pr-review/
│   └── SKILL.md     # Automated PR review checklist
├── deploy/
│   └── SKILL.md     # Pre-deploy validation + sequencing
├── commit/
│   └── SKILL.md     # Enforce commit message conventions
└── db-migration/
    └── SKILL.md     # Migration safety checks

Claude Code scans the .claude/skills/ directory at session start. By specifying the trigger command inside a SKILL.md file, typing a slash command like /pr-review in the chat loads that file and executes the procedure. Unlike CLAUDE.md, which occupies context for the entire session, skills are only loaded when invoked — so you save on token costs while keeping team procedures reusable.

# SKILL.md Example (pr-review/SKILL.md)
 
## PR Review Skill
 
This skill is invoked with the `/pr-review` command.
 
### Steps
 
1. Check the list of changed files with `git diff main...HEAD --name-only`
2. Review the following for each file, starting with the highest-impact ones:
   - [ ] TypeScript type safety (use of `any`, over-reliance on type inference)
   - [ ] Test coverage (existence of tests for new logic)
   - [ ] Security vulnerabilities (SQL injection, XSS, sensitive data exposure patterns)
   - [ ] Performance issues (N+1 queries, unnecessary re-renders)
3. Classify each issue by severity:
   - blocker: must fix before merging
   - major: recommended fix
   - minor: style suggestion
4. Output a summary report in markdown table format

⚠️ Warning: Skill files need version control just like code. It's common to put in the effort upfront only to have them go stale as the project evolves. It's recommended to build a routine for reviewing whether skill content still matches the current project on a quarterly basis.

Honestly, "if you're copying and pasting the same prompt more than twice a day" is a signal that it should become a skill. Pre-deploy checklists, PR review templates, commit message formats — these are the classic skill candidates.

Subagents — Delegating Parallel Work

Subagents are separate Claude instances running in independent context windows. The main agent acts as an orchestrator, distributing complex work across multiple subagents.

Main Agent (Opus — orchestration, complex reasoning)
├── frontend subagent (Sonnet) → UI component implementation
├── backend subagent (Sonnet) → API endpoint implementation
└── review subagent (Sonnet) → code review & security checks

To share my experience on model selection: I use Opus for the orchestrator. The reasoning required to decide how to split tasks and verify that subagent results don't conflict with each other is the critical part. Sonnet is sufficient for subagents handling actual implementation, and it's much better on speed and cost. Ultimately, the balance point is: complex judgment = Opus, focused execution = Sonnet, large-scale repetition = Haiku.

In foreground (synchronous) mode, the main agent waits for subagent results before proceeding to the next step. In background (asynchronous) mode, multiple subagents work concurrently.

📖 Context Window: The maximum amount of text an LLM can process at once. Since subagents each have their own independent context window, even if the main agent's context fills up, subagents can handle focused tasks with a clean slate.

Practical Application

Example 1: Automating New Hire Onboarding with Team CLAUDE.md + Custom Commands

This is a situation you encounter frequently in practice: when a new developer joins, it takes one to two weeks just to learn the team's conventions. The docs are outdated, and when you ask a senior developer you mostly hear "just read the code." Combining CLAUDE.md and custom commands lets the AI act as an onboarding partner that immediately knows the team's conventions.

# CLAUDE.md (shared across the entire team)
 
## Domain Knowledge
- User authentication uses JWT (with refresh token rotation)
- Payments are handled by a separate payment-service (no direct DB access)
- Deployment environments: staging (auto-deploy) → production (manual approval required)
 
## Notes for New Developers
- Always validate style with `pnpm lint` before generating code
- Recommended: run `/pr-review` command before creating a PR
- Required: run `/db-migration` command when changing the DB schema

# .claude/skills/onboarding/SKILL.md
 
## Onboarding Skill
 
This skill is invoked with the `/onboarding` command.
 
### Steps
 
1. Check dependencies and npm scripts with `cat package.json`
2. Understand TypeScript configuration with `cat tsconfig.json`
3. Understand top-level directory structure with `ls src/`
4. Explore key module structure with `find . -maxdepth 3 -name "*.module.ts" | head -20`
5. Cross-reference CLAUDE.md architecture rules against the actual directory structure
6. Output the following in markdown:
   - **Core directory structure** (up to 3 levels deep)
   - **Commonly used commands** (based on package.json scripts)
   - **Team conventions to watch out for** (summary of forbidden patterns from CLAUDE.md)
   - **Pre-first-PR checklist** (run lint, test, /pr-review)

When a new hire runs /onboarding, the AI directly analyzes the actual code and outputs an onboarding summary tailored to the team's conventions. Even when the documentation is outdated, it works much more accurately because it explains things from the code itself.

Example 2: Parallel Full-Stack Feature Development with Subagents

Instead of implementing frontend and backend sequentially when adding a new feature, you can use subagents to work on them simultaneously.

This is where git worktree comes in. Simply put, it's a feature that lets you check out the same repo into two different folders at the same time. A regular branch switch means only one branch can be active in one folder at a time, but with worktrees, ../project-frontend can maintain the frontend branch and ../project-backend can maintain the backend branch independently. This is the setup step that allows subagents to work in parallel without touching each other's files.

# Prepare Git worktrees
git worktree add ../project-frontend feature/user-profile-frontend
git worktree add ../project-backend feature/user-profile-backend

Now, by entering the following orchestration prompt directly into the Claude Code chat, the main agent runs both subagents simultaneously.

Implement the user profile editing feature.
Please run the following two subagents in parallel:
 
## Subagent 1 (frontend)
- Working directory: ../project-frontend
- Task: Implement the ProfileEditForm component
  - React Hook Form + zod schema validation
  - Avatar image upload (drag and drop)
  - Optimistic update handling
- Must comply with CLAUDE.md rules
 
## Subagent 2 (backend)
- Working directory: ../project-backend
- Task: Implement the PATCH /users/:id endpoint
  - DTO validation, image S3 upload handling
  - Transaction handling
- Must comply with CLAUDE.md rules
 
After completion, verify that both implementations agree on the API interface.

Example 3: Packaging Team AI Standards as a Plugin

You can bundle skills + hooks + MCP servers into a single installable unit and deploy it across teams. This is especially useful when multiple repos share the same standards.

team-ai-standard/          # Team AI standards plugin repo
├── .claude/
│   ├── skills/
│   │   ├── pr-review/SKILL.md
│   │   ├── deploy/SKILL.md
│   │   └── security-audit/SKILL.md
│   └── hooks/
│       ├── pre-commit.sh  # Auto-run lint before commit
│       └── post-test.sh   # Coverage report after tests
├── CLAUDE.md              # Common team rules
└── README.md              # Installation instructions

# Option 1: git submodule (pinned version — explicitly references a specific commit)
git submodule add https://github.com/your-team/team-ai-standard .claude-team
 
# Option 2: symbolic link (always latest — standards repo changes are reflected immediately)
ln -s .claude-team/.claude/skills .claude/skills/team

Summarizing the tradeoffs between the two approaches: submodules leave a record in Git history of exactly which version of the standards is in use, offering high stability, but updates must be explicitly triggered. Symbolic links automatically apply the latest version whenever you pull the standards repo, but it's easy to miss when the standards have changed. If your team is large and governance matters, choose submodules; for smaller teams, links are the more convenient choice.

Pros and Cons Analysis

Advantages

Disadvantages and Caveats

On the topic of costs — to be honest, when we first introduced subagents, the API bill came in at more than double what we expected. We were still using Opus for implementation tasks, and it wasn't until we dropped down to Sonnet that things settled to a reasonable level. Setting team-wide cost limits upfront is a good idea.

The Most Common Mistakes in Practice

1. The temptation to put everything in CLAUDE.md: Stuffing team conventions, onboarding guides, domain knowledge, and style guides all into a single file actually decreases the AI's instruction compliance rate. Keep CLAUDE.md for core rules only, and separate procedures into skills.

2. Delegating work to subagents without clear boundaries: Vague delegation like "build the backend and frontend at the same time" leads to subagents producing different interfaces that conflict at integration time. It's recommended to define the API contract (interface) first, then delegate.

3. Creating skills and abandoning them: Skills that were carefully built upfront often become outdated as the project evolves. CLAUDE.md and skills, like code, require PR reviews and version control. Build a routine for reviewing whether skill content still matches the current project on a quarterly basis.

Closing Thoughts

Combining all three layers — injecting team standards via CLAUDE.md, automating repetitive procedures with custom commands, and delegating parallel work to subagents — transforms the AI from a tool that needs a fresh briefing every session into a colleague that already knows the team's conventions.

The key insight that separates before and after reading this article: the problem of inconsistent AI behavior is not a limitation of the AI — it's a problem of context delivery structure. Once the structure is in place, the next new hire who joins and the least experienced person on the team can both get AI-generated code that conforms to team standards.

Three steps you can take starting right now:

1. Create a CLAUDE.md file in your project root today. Start by writing down in a ## Forbidden Patterns section anything the team has ever complained about with "the AI used a weird pattern again." Starting with 10 lines is enough.

2. If you have a prompt you copy and paste more than twice a day, consider extracting it into .claude/skills/<name>/SKILL.md. PR review checklists and pre-deploy validation procedures are good candidates. You'll be able to invoke it anytime with a /-prefixed command.

3. The next time you develop a full-stack feature, try subagent separation using git worktree. Running frontend and backend in parallel from independent directories lets you feel the speed difference firsthand.

References

• Claude Code Customization Complete Guide (CLAUDE.md, Skills, Subagents) | alexop.dev
• Understanding Claude Code Full Stack: MCP, Skills, Subagents, Hooks | alexop.dev
• How to Write a Good CLAUDE.md | HumanLayer Blog
• Claude Code Best Practices for Enterprise Teams | Portkey
• Practical Guide to Claude Code Subagents and Agent Teams | agentsroom.dev
• Complete Guide to Claude Code Skills: SKILL.md, MCP, Subagents & Teams (2026) | duet.so
• Claude Code Configuration Blueprint: The Complete Guide for Production Teams | DEV Community
• Sharing AI Development Rules Across Your Organization | Paul Duvall