Skip to main content

Claude.md Best Practices Research Report

Claude.md Best Practices Research Report

Research Date: December 3, 2025 Conducted By: AI Research Agent Purpose: Comprehensive analysis of Anthropic's official best practices for Claude.md files in Claude Code projects Sources: 25+ official Anthropic sources, engineering blogs, and documentation

Executive Summary​

Claude.md is a special Markdown file that Claude Code automatically loads into every conversation, serving as a persistent configuration layer for project-specific context. Based on comprehensive research of Anthropic's official documentation and engineering blogs, the following key findings emerged:

Critical Findings​

  1. Keep It Minimal: Under 300 lines (ideally under 100). Claude.md prepends to every prompt, consuming tokens and potentially introducing noise.

  2. Progressive Disclosure Architecture: Don't dump all information upfront. Use Claude.md to point to additional resources that Claude loads on-demand.

  3. Focus on Universal Content: Include only instructions that apply to every task. Task-specific guidance belongs in separate files or custom slash commands.

  4. Iterative Refinement: Treat Claude.md like a frequently-used prompt. Test what improves instruction-following rather than adding everything possible.

  5. Three-Tier Memory Hierarchy:

    • User-level (~/.claude/CLAUDE.md) - Personal preferences across all projects
    • Project-level (.claude/CLAUDE.md) - Team-shared conventions
    • Local project-level (.claude/CLAUDE.local.md) - Individual overrides

Performance Impact​

Research from Anthropic engineering indicates:

  • Frontier LLMs can follow ~150-200 instructions with reasonable consistency
  • Claude Code's system prompt already contains ~50 instructions
  • Bloated Claude.md files reduce performance and distract Claude
  • Each line costs tokens on every conversation turn

1. Official Anthropic Guidance​

1.1 What is Claude.md?​

From Anthropic's official documentation:

"Claude.md is a special file that Claude automatically incorporates into conversation context. Think of it as a configuration file that Claude automatically incorporates into every conversation."

Purpose​

  • Persistent project-specific context
  • Repository etiquette and conventions
  • Developer environment setup instructions
  • Frequently used commands
  • Architectural patterns and warnings

1.2 File Discovery Mechanism​

Hierarchical Loading (Cascading Order)​

Claude Code reads Claude.md files recursively: starting in the current working directory, it traverses up to (but not including) the root directory, reading all Claude.md or Claude.local.md files found.

File Locations (Priority Order)​

  1. Home directory: ~/.claude/CLAUDE.md - Universal preferences
  2. Parent directories: Support for monorepo setups
  3. Project root: .claude/CLAUDE.md - Team-shared (committed)
  4. Project root: .claude/CLAUDE.local.md - Personal (gitignored)
  5. Child directories: Loaded on-demand when Claude accesses those files

Multiple File Behavior​

"Claude.md files can be hierarchical, so you can have one project-level and one in nested directories, with Claude looking at them all and prioritizing the most specific, the most nested when relevant."

1.3 The /init Command​

Anthropic provides a /init command to bootstrap Claude.md files:

How it works​

  • Analyzes project structure (package files, configurations, code)
  • Generates starter Claude.md with detected patterns
  • Includes build commands, test instructions, conventions

Official Guidance​

"Think of /init as a starting point, not a finished product. The generated Claude.md captures obvious patterns but may miss nuances specific to your workflow. Review what Claude produces and refine it based on your team's actual practices."

Can be run on existing files​

"You can also use /init on existing projects that already have a Claude.md. Claude will review the current file and suggest improvements based on what it learns from exploring your codebase."

2.1 Core Sections (WHY, WHAT, HOW)​

From community best practices validated by Anthropic usage:

WHY - Project Purpose​

  • Brief description of what the project does
  • Function of major components
  • Architectural rationale for non-standard choices

WHAT - Tech Stack & Structure​

  • Technology stack with versions
  • Project structure overview
  • Key directories and their roles
  • Main dependencies
  • Codebase map for large projects

HOW - Commands & Workflows​

  • Build/run commands
  • Testing procedures
  • Linting and formatting
  • Deployment processes
  • Common development workflows

2.2 Essential Sections​

From Anthropic's official blog and documentation:

Minimum Viable Claude.md​

## Project Summary
[1-2 sentence description]

## Tech Stack
- [Language/Framework with version]
- [Key libraries]

## Key Directories
- `src/` - [purpose]
- `tests/` - [purpose]
- `docs/` - [purpose]

## Common Commands
- Build: `[command]`
- Test: `[command]`
- Lint: `[command]`
- Dev server: `[command]`

## Standards
- [Critical coding standards]
- [Type requirements]
- [Style guidelines reference]

2.3 Advanced Sections (When Needed)​

For Complex Projects​

  1. Architectural Patterns

    • Domain-driven design approach
    • Microservices boundaries
    • Non-standard architecture choices
    • Why specific patterns were chosen

  2. Team Conventions

    • Branch naming schemes
    • Commit message format
    • Code review requirements
    • PR templates

  3. Custom Tools & MCP Servers

    • Available MCP servers with usage examples
    • Custom tooling configurations
    • Non-standard development tools

  4. Workflows

    • Step-by-step process for new features
    • Bug fix workflow
    • Code review process
    • Deployment checklist

  5. Critical Warnings

    • Rate limits for external services
    • Performance-sensitive code regions
    • Security considerations
    • Known gotchas or edge cases

2.4 Example Structure from Anthropic's Quickstarts​

From the official anthropic-quickstarts repository:

## Project Name

### Setup
- Environment: `[setup command]`
- Dependencies: `[install command]`
- Build: `[build command]`

### Development
- Dev server: `[run command]`
- Hot reload: [if applicable]

### Code Quality
- Linting: `[lint command]`
- Type checking: `[type-check command]`
- Testing: `[test command]`

### Style Conventions
- Naming: [conventions]
- Organization: [patterns]
- Imports: [sorting/grouping rules]

### Architecture
- [Key architectural patterns]
- [Component organization]
- [Data flow]

3. Content Guidelines​

3.1 What to Include​

From Official Anthropic Guidance​

✅ DO Include:

  • Build/run commands with examples
  • Testing procedures and framework details
  • Key architectural decisions
  • Team-specific conventions
  • Critical warnings about code regions
  • Rate limits for external services
  • Frequently used bash commands with descriptions
  • Core files and utility functions
  • Repository etiquette (branching, merge strategies)
  • Developer environment setup requirements
  • Project-specific quirks or warnings

3.2 What to Exclude​

From Official Anthropic Guidance & Best Practices​

❌ DON'T Include:

  1. Code Style Guidelines - Use linters instead

    "Never send an LLM to do a linter's job - LLMs are comparably expensive and incredibly slow compared to traditional linters."

  2. Sensitive Data

    • API keys, credentials, or security vulnerabilities
    • Especially important if version-controlled

  3. Task-Specific Instructions

    • Instructions that don't apply to every task
    • Use separate markdown files or custom commands instead

  4. Documentation File @-mentions

    "Don't @-mention documentation files in your Claude.md as this bloats the context window by embedding the entire file on every run."

  5. Excessive Content Without Testing

    "A common mistake is adding extensive content without iterating on its effectiveness."

  6. Long Narrative Paragraphs

    "You're writing for Claude, not onboarding a junior dev - use short, declarative bullet points and don't write long, narrative paragraphs."

  7. Theoretical Guidance

    • Information exceeding practical utility
    • Unrelated project documentation
    • "Best practices" that don't match your actual workflow

3.3 Content Formatting Best Practices​

From Multiple Anthropic Sources​

  1. Be Specific and Declarative

    • "Use 2-space indentation" > "Format code nicely"
    • Concrete examples > abstract principles
    • Short bullet points > paragraphs

  2. Use Structured Organization

    • Markdown headings for sections
    • Bullet points for related items
    • Code blocks for commands
    • Consistent hierarchy

  3. Anti-Bloat Rules

    • Don't add "Warning Signs" to obvious rules
    • Don't show bad examples for trivial mistakes
    • Don't write paragraphs explaining what bullets can summarize
    • Keep under 100 lines if possible

  4. Command Documentation Pattern

## Common Commands

### Development
- Start dev server: `npm run dev` - Launches on port 3000
- Run tests: `npm test` - Uses Jest with coverage
- Lint code: `npm run lint` - ESLint with auto-fix

### Building
- Production build: `npm run build` - Outputs to dist/
- Type check: `npm run typecheck` - TypeScript strict mode

4. Token Efficiency & Context Management​

4.1 Progressive Disclosure Pattern​

Core Principle from Anthropic Engineering​

"Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable."

Implementation Strategy​

Instead of dumping all information into Claude.md, use it to reference additional resources:

## Additional Documentation

For specific tasks, refer to:
- `docs/frontend-development.md` - Component patterns
- `docs/api-integration.md` - Backend integration guide
- `docs/testing-strategy.md` - Test writing guidelines

Claude will read these files when working on related tasks.

4.2 Three-Tier Architecture​

From Agent Skills Research​

  1. Metadata Layer (Always Loaded) - Claude.md basics
  2. Full Content Layer (Conditionally Loaded) - Referenced docs
  3. Referenced Files (As-Needed) - Deep documentation

Benefits​

  • Minimal token consumption baseline
  • Unbounded context potential
  • Focused information retrieval

4.3 Context Window Management​

Official Best Practices​

  1. Use /clear Command Frequently

    "During long sessions, Claude's context window can fill with irrelevant conversation, file contents, and commands, which can reduce performance and distract Claude. Use the /clear command frequently between tasks to reset the context window."

  2. Avoid Final 20% for Complex Tasks

    "Avoid using the final 20% of your context window for complex tasks, as performance degrades significantly when approaching limits."

  3. Leverage Subagents

    "For complex problems, consider strong use of subagents, especially early on in a conversation or task."

  4. Structured State Files

    • Use claude-progress.txt for session notes
    • Use feature_list.json for structured data
    • Use tests.json for test status tracking
    • Git history provides recoverable checkpoints

4.4 Token Optimization Strategies​

From Anthropic Engineering Blogs​

  1. Just-in-Time Context Loading

    • Store lightweight identifiers (file paths, queries)
    • Load full content only when needed
    • Use grep/glob for progressive discovery

  2. Compaction

    • Summarize conversation history near context limits
    • Preserve architectural decisions, bugs, implementation details
    • Discard redundant outputs

  3. Structured Note-Taking

    • External memory files (NOTES.md, to-do lists)
    • Pull back into context when needed
    • Maintain coherence across context resets

  4. Sub-Agent Architectures

    • Specialized sub-agents for focused tasks
    • Return condensed summaries (1,000-2,000 tokens)
    • Lead agent coordinates with high-level plan

5. Multi-Session Continuity Patterns​

5.1 Long-Running Agent Architecture​

From "Effective Harnesses for Long-Running Agents"​

Anthropic's two-agent solution for multi-session continuity:

Components​

  1. Initializer Agent - First-run setup
  2. Coding Agent - Subsequent sessions with identical system prompt/tools

State Files​

  • claude-progress.txt - Chronological work log
  • feature_list.json - Feature status (use JSON, not Markdown)
  • init.sh - Environment setup script
  • Git history - Recoverable checkpoints

Why JSON for Feature Lists​

"The model is less likely to inappropriately change or overwrite JSON files compared to Markdown files."

5.2 Session Continuity Strategies​

Opening Ritual (Every Session)​

  1. Verify working directory
  2. Read progress notes
  3. Examine feature list
  4. Check git logs
  5. Launch development server
  6. Run baseline tests

Incremental Work Discipline​

  • Focus on single features per session
  • Prevents context exhaustion mid-feature
  • Clear handoff points between sessions

Clean State Requirements​

  • Conclude with git commits
  • Update progress files
  • Enable rollback if needed
  • Mimic professional developer practices

5.3 Component Activation Pattern​

From Anthropic's Multi-Session Research​

feature_list.json Structure​

{
  "features": [
    {
      "category": "authentication",
      "description": "User login system",
      "verification": [
        "Run dev server",
        "Navigate to /login",
        "Test valid credentials",
        "Verify dashboard redirect"
      ],
      "passes": true
    }
  ]
}

Benefits​

  • Structured format prevents accidental modification
  • Clear verification steps
  • Boolean status tracking
  • Category organization

6. Communication Style & Tone​

6.1 Writing for AI vs. Humans​

Key Insight from Best Practices​

"You're writing for Claude, not onboarding a junior dev - use short, declarative bullet points and don't write long, narrative paragraphs."

Preferred Style​

  • Concise, declarative statements
  • Bullet points over paragraphs
  • Specific over generic
  • Action-oriented over explanatory

6.2 Output Style Configuration​

From Claude Code Documentation​

Claude supports multiple communication styles via /output-style:

  • Normal - Default balanced responses
  • Concise - Shorter, more direct responses
  • Explanatory - Educational with additional detail
  • Formal - Clear and polished text
  • Custom - User-defined via Markdown files

Configuration Levels​

  • Project-level: .claude/output-styles/[name].md
  • User-level: ~/.claude/output-styles/[name].md

6.3 Instruction Emphasis​

From Anthropic's Best Practices​

"Anthropic runs Claude.md files through their prompt improver tool and uses emphasis techniques (like 'IMPORTANT' or 'YOU MUST') to strengthen adherence to critical instructions."

## Critical Requirements

**IMPORTANT:** Always run tests before committing code.

**YOU MUST:** Use type hints for all function parameters.

**NEVER:** Commit directly to main branch.

Use sparingly - Overuse reduces effectiveness.

7. Do's and Don'ts​

7.1 Do's​

✅ DO: Keep Files Minimal

  • Under 300 lines total
  • Under 100 lines ideally
  • Every line should solve a real problem

✅ DO: Use Progressive Disclosure

  • Reference additional docs in Claude.md
  • Let Claude load detailed content on-demand
  • Organize related docs in subdirectories

✅ DO: Iterate and Test

  • Treat Claude.md like a frequently-used prompt
  • Test what actually improves instruction-following
  • Remove content that doesn't help

✅ DO: Use # Key for Dynamic Updates

"Press the # key during sessions to have Claude automatically incorporate instructions into the relevant Claude.md file."

✅ DO: Check into Version Control

  • Share .claude/CLAUDE.md with team
  • Maintain consistency across team members
  • Document architectural patterns everyone should follow

✅ DO: Use Claude.local.md for Personal Preferences

  • Add to .gitignore
  • Keep personal/experimental instructions separate
  • Avoid cluttering shared documentation

✅ DO: Leverage Hooks & Commands

  • Use hooks for formatters/linters
  • Use slash commands for code-style guidance
  • Automate repetitive validations

✅ DO: Include Verification Steps

  • How to run development server
  • How to execute tests
  • How to validate changes

7.2 Don'ts​

❌ DON'T: Stuff Everything Possible

"Don't stuff every possible command into the file—you will get sub-optimal results."

❌ DON'T: Use /init Without Review

"Don't auto-generate with /init—it's the highest leverage point of the harness."

❌ DON'T: Include Code Style in Claude.md

  • Use linters (Ruff, ESLint, etc.)
  • Use formatters (Black, Prettier, etc.)
  • Use hooks for automatic formatting

❌ DON'T: @-Mention Documentation Files

  • Bloats context window
  • Embeds entire files on every run
  • Use references instead

❌ DON'T: Add Theoretical Content

  • Focus on actual workflow
  • Solve real problems encountered
  • Skip "best practices" that don't apply

❌ DON'T: Create Too Many Complex Commands

"If you have a long list of complex, custom slash commands, you've created an anti-pattern."

❌ DON'T: Jump to Implementation

"One of the most common mistakes is jumping straight into implementation without a clear plan."

❌ DON'T: Make Roadmaps Too Complex

  • Keep tracking simple
  • Avoid dumping every random idea
  • Focus on actionable items

7.3 Common Anti-Patterns​

From Multiple Best Practice Sources​

  1. Context Bloat

    • Long Claude.md files (>300 lines)
    • Embedding full documentation
    • Repeating information

  2. Excessive Instructions Without Testing

    • Adding content without validation
    • Including theoretical guidelines
    • Not iterating based on results

  3. Poor Organization

    • Paragraphs instead of bullets
    • Lack of clear sections
    • Inconsistent formatting

  4. Wrong Tool for the Job

    • Using LLMs for linting
    • Manual checks instead of automation
    • Complex workflows without hooks

  5. Not Using Progressive Disclosure

    • Dumping all information upfront
    • Not referencing external docs
    • Ignoring subdirectory organization

8. Source Bibliography​

8.1 Official Anthropic Sources​

Primary Documentation​

  1. Claude Code Overview - Official documentation
  2. Claude Code Settings - Configuration guide
  3. Common Workflows - Usage patterns
  4. Slash Commands - Custom command documentation

Engineering Blog Posts​

  1. Claude Code Best Practices - Official best practices
  2. Effective Harnesses for Long-Running Agents - Multi-session patterns
  3. Effective Context Engineering for AI Agents - Progressive disclosure
  4. Equipping Agents with Agent Skills - Skills architecture

Official Resources​

  1. Using Claude.md Files - Official blog guide
  2. How Anthropic Teams Use Claude Code - Internal usage patterns

GitHub Repositories​

  1. anthropics/anthropic-quickstarts - Official examples
  2. anthropics/Claude-code - Main repository

8.2 Authoritative Community Sources​

Best Practice Guides​

  1. Writing a Good Claude.md - Comprehensive guide
  2. Apidog: Claude.md Best Practices - 5 best practices
  3. ClaudeLog Documentation - Community resource hub

Real-World Examples​

  1. ArthurClune/Claude-md-examples - Production examples
  2. Playbooks: Claude.md Examples - Practical templates

Technical Guides​

  1. Managing Claude Code's Context - Context management handbook
  2. Cooking with Claude Code - Complete guide
  3. Claude Code Professional Guide - Frontend focus

Advanced Topics​

  1. Writing Claude.md for Mature Codebases - Enterprise patterns
  2. Learning from Anthropic: Nested Skills - Skill organization
  3. Progressive Disclosure in Agent Skills - Architecture analysis

Tool & Configuration​

  1. Claude Code Cheat Sheet - Commands and configuration
  2. Claude Memory Deep Dive - Memory systems

9. Examples from Official Sources​

9.1 Minimal Example (Anthropic Blog)​

# Project: FastAPI REST API

## Tech Stack
- Python 3.11+ (3.12 preferred)
- FastAPI for API framework
- SQLAlchemy for database operations
- Pydantic for validation
- PostgreSQL database

## Key Directories
- `app/` - Application code
- `app/models/` - Database models
- `app/routes/` - API endpoints
- `tests/` - Test suite

## Common Commands
- Install: `uv sync`
- Dev server: `uvicorn app.main:app --reload`
- Tests: `pytest`
- Lint: `ruff check .`
- Format: `ruff format .`

## Standards
- Type hints required for all code
- Use PEP 8 naming conventions
- Prioritize readability over cleverness
- Ask clarifying questions before architectural changes

9.2 Python Project (ArthurClune Examples)​

# Python Development Guidelines

## Core Development Rules

**Package Management:**
- Use `uv` for all package operations (never pip)
- Update `pyproject.toml` for dependencies

**Code Quality:**
- Type hints required for all code
- Use pytest for testing
- Follow PEP 8 naming conventions

## Development Philosophy

1. **Simplicity & Readability** - Clear code over clever code
2. **Performance** - Consider efficiency for critical paths
3. **Maintainability** - Write code others can understand
4. **Testability** - Design for easy testing
5. **Minimal Footprint** - Keep code concise

## Coding Best Practices

- **Early Returns** - Reduce nesting depth
- **Descriptive Names** - Self-documenting code
- **DRY Principle** - Avoid repetition
- **Functional Approach** - Prefer pure functions
- **Iterative Building** - Small, tested increments

## Code Formatting

- Tool: `ruff` for formatting and checking
- Type checking: `pyright`
- Line length: 88 characters
- Import sorting: `isort` with combine-as-imports
- Pre-commit hooks for automatic checks

9.3 TypeScript/React (Anthropic Quickstarts)​

# Customer Support Agent

## Setup
- Install: `npm install`
- Dev server: `npm run dev`

## Tech Stack
- Next.js 14 (App Router)
- TypeScript (strict mode)
- React 18
- shadcn/ui components
- Tailwind CSS

## Development Variants
- Full UI: `npm run dev`
- Left sidebar only: `npm run dev:left`
- Right sidebar only: `npm run dev:right`
- Chat only: `npm run dev:chat`

## Code Standards
- Use function components with React hooks
- Strict TypeScript mode enabled
- ESLint configuration with Next.js rules
- Import shadcn/ui components from `@/components/ui`

## Architecture
- Server components by default
- Client components marked with 'use client'
- API routes in `app/api/`
- Components in `components/`

9.4 Infrastructure as Code (ArthurClune)​

# Terraform Development

## Setup
- Terraform 1.5+
- AWS CLI configured
- Required providers: AWS, Random

## Project Structure
- `main.tf` - Primary resources
- `variables.tf` - Input variables
- `outputs.tf` - Output values
- `versions.tf` - Provider versions
- `terraform.tfvars` - Variable values (gitignored)

## Common Commands
- Initialize: `terraform init`
- Plan: `terraform plan`
- Apply: `terraform apply`
- Destroy: `terraform destroy`

## Best Practices
- Always run plan before apply
- Use workspaces for environments
- Tag all resources appropriately
- Follow naming conventions: `[env]-[service]-[resource]`
- Never commit terraform.tfvars

10. Recommendations for CODITECT​

10.1 Current State Analysis​

CODITECT's Existing Claude.md Files​

  • Three hierarchical files (master, submodule core, local .Claude)
  • Total combined length: ~1,500+ lines
  • Rich with context, agents, skills, commands

Alignment with Best Practices​

  • ✅ Hierarchical organization matches Anthropic patterns
  • ✅ Comprehensive component documentation
  • ⚠️ File length significantly exceeds recommendations
  • ⚠️ Could benefit from progressive disclosure
  • ⚠️ Some content could move to on-demand loading

Three-Tier Architecture​

  1. Tier 1: Master Claude.md (Root) - 100-150 lines

    • Project overview and philosophy
    • Submodule structure
    • Git workflow basics
    • Common cross-cutting commands
    • References to detailed documentation

  2. Tier 2: Submodule Claude.md - 150-200 lines

    • Submodule-specific context
    • Component activation patterns
    • Agent/skill/command summaries
    • References to component directories
    • Task-specific workflows

  3. Tier 3: Component Documentation - Loaded on-demand

    • Individual agent definitions
    • Skill specifications
    • Command implementations
    • Detailed workflow documentation

10.3 Progressive Disclosure Implementation​

Current Approach​

## 🚀 Slash Command Quick Start (in CLAUDE.md)
[Long section with all command details]

## 🚀 Slash Commands

CODITECT provides 81+ slash commands organized by category.

**Quick References:**
- View all commands: Read `.claude/commands/README.md`
- Agent selection: Use `/suggest-agent` or `/agent-dispatcher`
- Command syntax: See `.claude/docs/SLASH-COMMANDS-REFERENCE.md`
- Workflow patterns: Review `.claude/commands/COMMAND-GUIDE.md`

**Most Common:**
- `/new-project` - Create production-ready project
- `/git-sync` - Synchronize submodules
- `/analyze-hooks` - Assess hooks implementation

10.4 Specific CODITECT Optimizations​

1. Component Activation Section​

Current: Long explanations embedded in Claude.md

Recommended:

## Component Activation

Components require explicit activation before use.

**Status Check:** `python3 scripts/update-component-activation.py status [type] [name]`
**Activate:** `python3 scripts/update-component-activation.py activate [type] [name]`
**Details:** See `docs/04-project-planning/COMPONENT-ACTIVATION-GUIDE.md`

**Current Status:** 11 activated of 301 total components (lean activation strategy)

2. Agent Framework Section​

Current: Extensive agent descriptions inline

Recommended:

## AI Agent Framework

**All Specialized Agents** available via Task() invocation.

**Common Agents:**
- `orchestrator` - Multi-agent coordination
- `codi-documentation-writer` - Documentation generation
- `git-workflow-orchestrator` - Git automation
- `session-analysis-agent` - Session tracking

**Full Catalog:** See `AGENT-INDEX.md` for complete list
**Usage Patterns:** See `docs/02-user-guides/AGENT-USAGE-GUIDE.md`
**Invocation:** Use Task Tool Proxy Pattern (verified working method)

3. Multi-Session Context​

Current: Detailed technical implementation

Recommended:

## Multi-Session Integration

**Reality Check:** Components require manual activation (not auto-loaded).

**Quick Start:**
1. Search for components: Use Grep on `agents/`, `skills/`, `commands/`
2. Check activation: Read `.coditect/component-activation-status.json`
3. Request activation: Provide human with command
4. Use component: After human activates

**Complete Guide:** See `docs/MULTI-SESSION-INTEGRATION-GUIDE.md`
**Session Scripts:** `scripts/session-analyzer.py` (always available, no activation)

4. Git Workflow Section​

Current: Embedded workflow details

Recommended:

## Git Workflow

**Bottom-up synchronization** with conventional commits.

**Quick Commands:**
- Full sync: `/git-sync --target all --mode full`
- Dry run: `/git-sync --target all --dry-run`
- Analysis: `/git-sync --mode analyze`

**Pre-push Hook:** Prevents out-of-sync pushes automatically
**Complete System:** See `docs/GIT-WORKFLOW-SYSTEM.md`

10.5 CODITECT Claude.md Template​

# CODITECT Rollout Master - Claude Code Configuration

## Project Overview

Master orchestration repository coordinating 49 git submodules across 8 categories
for complete AZ1.AI CODITECT platform rollout.

**Current Phase:** Beta Testing (Active)
**Architecture:** Distributed intelligence via .coditect symlink chains

## Essential Reading Priority

1. **WHAT-IS-CODITECT.md** - Distributed intelligence architecture (CRITICAL)
2. **README.md** - Repository overview and navigation
3. **project-plan.md** - Complete rollout strategy
4. **tasklist.md** - 530+ tasks with checkbox tracking
5. **Subdirectory CLAUDE.md** - Task-specific context

## Repository Structure

CODITECT-rollout-master/ ├── .CODITECT -> submodules/core/CODITECT-core # CODITECT brain ├── .Claude -> .CODITECT # Compatibility ├── docs/ - Master documentation ├── diagrams/ - C4 architecture (24 diagrams) ├── scripts/ - Automation (19 Python + 6 shell) ├── submodules/ - 46 repositories (8 categories) └── MEMORY-CONTEXT/ - Session exports


## Hierarchical CLAUDE.md Files

**Master (you are here)** - Orchestration and submodule coordination
**docs/project-management/** - PROJECT-PLAN/TASKLIST updates, sprint planning
**docs/adrs/** - Architecture decisions and technology choices
**docs/security/** - Security operations and compliance
**scripts/** - Automation script execution
**Submodule specific** - Navigate to submodule for specialized context

## Git Workflow (CRITICAL)

**Always commit in submodule FIRST, then update pointer in master.**

In submodule:​

cd submodules/[category]/[name] git checkout main && git pull

Make changes​

git add . && git commit -m "feat: Description" && git push

In master:​

cd ../../.. git add submodules/[category]/[name] git commit -m "Update [name]: Description" && git push


**Automated Sync:** `/git-sync --target all --mode full`
**Documentation:** `docs/GIT-WORKFLOW-SYSTEM.md`

## CODITECT Framework (Submodule Core)

**all components** available via submodule:

- all agents, all commands, all skills, all scripts, prompts, hooks
- 11 activated, 290 available on-demand (lean activation)
- Manual activation required (prevents auto-loading bloat)

**Quick References:**

- Component catalog: `.coditect/COMPLETE-INVENTORY.md`
- Agent index: `.coditect/AGENT-INDEX.md`
- Slash commands: `.coditect/docs/SLASH-COMMANDS-REFERENCE.md`

**Activation:**

```bash

cd submodules/core/coditect-core
python3 scripts/update-component-activation.py activate [type] [name] --reason "[why]"

Development Workflow​

  1. EXPLORE - Read project-plan.md and tasklist.md
  2. PLAN - Identify submodules needing changes
  3. CODE - Work in one submodule at a time
  4. COMMIT - Checkpoint work with scripts/create-checkpoint.py

Common Tasks​

Sync Submodules: ./scripts/sync-all-submodules.sh Create Checkpoint: python3 .coditect/scripts/create-checkpoint.py "Description" --auto-commit Regenerate Timeline: cd scripts && python generate-enhanced-timeline.py Verify System: ./scripts/verify-distributed-intelligence.sh

Human Approval Required​

  • Architecture changes affecting multiple submodules
  • New dependencies or technology additions
  • Budget changes (>$5K)
  • Timeline adjustments
  • Security-related changes

Session Management​

Context Files:

  • MEMORY-CONTEXT/sessions/ - Session exports
  • MEMORY-CONTEXT/checkpoints/ - Sprint checkpoints
  • MEMORY-CONTEXT/dedup_state/ - Deduplicated messages

Always create checkpoints after completing work.

Additional Documentation​

For detailed information, see:

  • Multi-session patterns: docs/MULTI-SESSION-INTEGRATION-GUIDE.md
  • Docker development: submodules/core/coditect-core/docs/05-deployment/
  • Best practices: submodules/core/coditect-core/docs/CLAUDE-4.5-BEST-PRACTICES.md
  • Complete workflows: Subdirectory Claude.md files

Status​

Phase: Beta Testing (Week 3 of 4) Launch: March 11, 2026 (99 days remaining) Components: 301 total, 11 activated Documentation: 456K+ words

Last Updated: 2025-12-03 Repository: https://github.com/coditect-ai/coditect-rollout-master Owner: AZ1.AI INC


### 10.6 Implementation Roadmap

#### Phase 1: Refactor Master CLAUDE.md (1-2 hours)

- Extract detailed content to separate docs
- Keep master to 100-150 lines
- Add references to detailed documentation
- Test with Claude Code session

#### Phase 2: Refactor Submodule CLAUDE.md (2-3 hours)

- Move component details to on-demand files
- Keep core to 150-200 lines
- Improve progressive disclosure
- Test component discovery workflow

#### Phase 3: Create On-Demand Documentation (3-4 hours)

- Multi-session integration guide
- Component activation detailed guide
- Agent usage comprehensive guide
- Workflow detailed documentation

#### Phase 4: Validation (1-2 hours)

- Test with fresh Claude Code session
- Verify component discovery works
- Measure token usage reduction
- Gather feedback and iterate

#### Expected Benefits

- 70-80% reduction in CLAUDE.md token consumption
- Faster session startup (less context to load)
- Better instruction-following (under 150 total instructions)
- Improved component discovery workflow
- Maintained completeness via progressive disclosure

---

## Conclusion

Anthropic's official guidance emphasizes **minimalism, progressive disclosure, and iterative refinement** for CLAUDE.md files. The research consistently shows that:

1. **Shorter is better** - Under 300 lines total, under 100 lines ideal
2. **Progressive disclosure works** - Reference external docs instead of embedding everything
3. **Iteration is critical** - Test what improves instruction-following
4. **Frontier LLMs have limits** - ~150-200 instructions max with reasonable consistency
5. **Token efficiency matters** - CLAUDE.md prepends to every prompt

### For CODITECT

- Current approach is comprehensive but could benefit from progressive disclosure
- Refactoring to three-tier architecture would align with best practices
- Expected 70-80% token reduction while maintaining completeness
- Improved instruction-following and session performance

#### Key Takeaway

> "Your CLAUDE.md file should contain as few instructions as possible - ideally only ones which are universally applicable to your task, as instruction-following quality decreases uniformly as instruction count increases."

---

**Research Compiled By:** AI Research Agent
**Date:** December 3, 2025
**Sources:** 25+ official Anthropic and authoritative community sources
**Confidence Level:** High (based on multiple corroborating official sources)
**Recommended Action:** Implement progressive disclosure refactoring for CODITECT