CODITECT CLAUDE.md Standard

Purpose

This standard defines requirements for CLAUDE.md files - the AI agent context files that help Claude Code understand project structure, conventions, and workflows.

Scope

Applies to:

• Root CLAUDE.md in every CODITECT repository
• Directory CLAUDE.md files for hierarchical context
• Customer projects using CODITECT framework

---

1. Core Principles

1.1 CLAUDE.md Philosophy

Principle	Description
Concise	Keep under 150 lines (project) or 200 lines (submodule)
Actionable	Focus on what Claude needs to DO
Hierarchical	Use subdirectory CLAUDE.md for deep context
Token-efficient	Every token should provide value

1.2 What Goes in CLAUDE.md

Include	Exclude
Project structure overview	Detailed documentation
Critical directives	Full API references
Quick reference commands	Historical information
Safety warnings	Marketing content
Key file locations	Exhaustive file lists
Common task patterns	Rarely-used information

---

2. Required Sections

2.1 Minimum Structure

# Project Name

## Overview

Brief description (2-3 sentences).

## Quick Reference

Key commands and actions.

## Project Structure

Essential directory layout.

## Common Tasks

How to do frequent operations.

2.2 Recommended Structure (Full)

# Project Name

## Quick Reference

Table of common actions.

## Critical Directives

Safety warnings, required approvals.

## Project Structure

Directory layout with key paths.

## Key Files

Important files and their purposes.

## Common Tasks

Step-by-step for frequent operations.

## Conventions

Naming, coding, commit standards.

## Troubleshooting

Common issues and solutions.

---

3. Section Guidelines

3.1 Quick Reference

Use a compact table format:

## Quick Reference

| Action | Command |
|--------|---------|
| Start dev | `npm run dev` |
| Run tests | `npm test` |
| Build | `npm run build` |
| Deploy | `./deploy.sh` |

3.2 Critical Directives

Use blockquotes for emphasis:

## Critical Directives

> **NEVER delete files without explicit user permission.**

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

3.3 Project Structure

Show essential structure only:

## Project Structure

project/ ├── src/ # Source code ├── tests/ # Test files ├── docs/ # Documentation ├── scripts/ # Automation └── config/ # Configuration

3.4 Common Tasks

Provide copy-paste commands:

## Common Tasks

### Run Tests

```bash
npm test

Deploy to Production

./scripts/deploy.sh --env production

---

## 4. Length Guidelines

### 4.1 By Repository Type

| Type | Max Lines | Rationale |
|------|-----------|-----------|
| Project root | 150 | Quick context loading |
| Submodule root | 200 | More domain-specific context |
| Directory CLAUDE.md | 50 | Focused scope |
| Standards/Framework | 250 | Reference documentation |

### 4.2 Token Budget

Estimate ~4 characters per token:

| Lines | Approx Tokens | Grade |
|-------|---------------|-------|
| <100 | ~400 | Excellent |
| 100-150 | ~600 | Good |
| 150-200 | ~800 | Acceptable |
| >200 | >800 | Review for reduction |

---

## 5. Hierarchical Context

### 5.1 Directory Inheritance

Claude reads CLAUDE.md files hierarchically:

project/ ├── CLAUDE.md # Project-wide context (read first) ├── src/ │ └── CLAUDE.md # Source code context (adds to above) ├── docs/ │ └── CLAUDE.md # Documentation context └── scripts/ └── CLAUDE.md # Script-specific context

### 5.2 When to Create Directory CLAUDE.md

Create if directory has:
- Unique conventions different from parent
- Complex workflows specific to that directory
- Frequently accessed by Claude for tasks
- Domain-specific knowledge needed

---

## 6. Templates

### 6.1 Minimal Template

```markdown
# Project Name

## Overview

Brief description of the project.

## Quick Reference

| Action | Command |
|--------|---------|
| Setup | `npm install` |
| Run | `npm start` |
| Test | `npm test` |

## Key Files

- `src/index.ts` - Main entry point
- `config/` - Configuration files

6.2 Standard Template

# Project Name

## Quick Reference

| Action | Command |
|--------|---------|
| Setup | `npm install` |
| Dev | `npm run dev` |
| Build | `npm run build` |
| Test | `npm test` |
| Deploy | `./scripts/deploy.sh` |

## Critical Directives

> **Always run tests before committing.**

> **Never commit secrets or .env files.**

## Project Structure

project/ ├── src/ # Source code ├── tests/ # Tests ├── docs/ # Documentation └── scripts/ # Automation

## Key Files

| File | Purpose |
|------|---------|
| `src/index.ts` | Application entry |
| `config/app.json` | App configuration |
| `scripts/deploy.sh` | Deployment script |

## Common Tasks

### Add New Feature

1. Create branch: `git checkout -b feature/name`
2. Implement in `src/features/`
3. Add tests in `tests/`
4. Run tests: `npm test`
5. Create PR

### Fix Bug

1. Reproduce issue
2. Write failing test
3. Fix code
4. Verify test passes
5. Commit with `fix:` prefix

## Conventions

- **Commits:** Conventional commits (`feat:`, `fix:`, `docs:`)
- **Branches:** `feature/`, `fix/`, `docs/` prefixes
- **Code:** ESLint + Prettier enforced

---

**Last Updated:** YYYY-MM-DD

6.3 Framework Template

See templates/CLAUDE-MD-TEMPLATE.md for comprehensive framework template.

---

7. Anti-Patterns

7.1 Avoid These

Anti-Pattern	Problem	Solution
>200 lines	Token waste, slow context	Split to hierarchy
Full file listings	Unnecessary detail	Show structure only
Duplicate info	Redundant tokens	Single source of truth
No quick reference	Hard to find actions	Add table at top
Missing directives	Safety risks	Add critical warnings
Outdated commands	Broken workflows	Keep synchronized

7.2 Examples

❌ WRONG - Too verbose
## Files
- src/index.ts - The main entry point that initializes the application
- src/config.ts - Configuration loading and validation module
- src/utils/helpers.ts - Utility helper functions
[... 50 more lines of files ...]

✅ CORRECT - Concise
## Key Files
| File | Purpose |
|------|---------|
| `src/index.ts` | Main entry |
| `src/config.ts` | Configuration |
| `src/utils/` | Utility functions |

---

8. Validation

8.1 Checklist

• Under line limit (150/200)
• Has Quick Reference section
• Has Project Structure
• Critical directives marked clearly
• Commands are copy-paste ready
• No redundant information
• Updated date present

8.2 Automated Validation

# Check CLAUDE.md compliance
/claude-md-check path/to/CLAUDE.md

# Show line count and token estimate
wc -l CLAUDE.md

---

9. Quality Grades

Grade	Lines	Content	Description
A	<100	Complete	Exemplary, minimal tokens
B	100-150	Complete	Production-ready
C	150-200	Complete	Acceptable, review for reduction
D	>200	Complete	Too long, needs splitting
F	Any	Incomplete	Missing critical sections

---

References

• CODITECT-STANDARD-CLAUDE-MD.md - Full specification
• FILE-NAMING-CONVENTIONS.md - Naming rules
• templates/CLAUDE-MD-TEMPLATE.md - Copy-paste templates

---

Version: 1.0.0 Status: Active Owner: CODITECT Core Team Last Updated: 2026-01-02