Writing CLAUDE.md Skill

Writing CLAUDE.md

Overview

Writing CLAUDE.md IS establishing a constitution for your project.

The <law> block mechanism forces Claude to actively repeat constraints each response, preventing context drift over long conversations.

Core principle: Laws without Self-Reinforcing Display drift out of context. The display IS the enforcement.

Violating the letter of the rules is violating the spirit of the rules.

Task Initialization (MANDATORY)

Before ANY action, create task list using TaskCreate:

TaskCreate for EACH task below:
- Subject: "[writing-claude-md] Task N: <action>"
- ActiveForm: "<doing action>"

Tasks:

Analyze current state
RED - Test without proper laws
GREEN - Write constitution
Add project content
Validate structure
REFACTOR - Quality review
Test with new session

Announce: "Created 7 tasks. Starting execution..."

Execution rules:

TaskUpdate status="in_progress" BEFORE starting each task
TaskUpdate status="completed" ONLY after verification passes
If task fails → stay in_progress, diagnose, retry
NEVER skip to next task until current is completed
At end, TaskList to confirm all completed

TDD Mapping for CLAUDE.md

| TDD Phase | CLAUDE.md Creation | What You Do | |-----------|-------------------|-------------| | RED | Test without laws | Observe agent without proper <law> block | | Verify RED | Document drift | Note where agent forgot constraints | | GREEN | Write constitution | Create <law> block addressing drift | | Verify GREEN | Test enforcement | Verify laws displayed every response | | REFACTOR | Improve laws | Make laws more specific, verifiable |

Task 1: Analyze Current State

Goal: Understand what exists and what's needed.

If CLAUDE.md exists:

Read current content
Check for <law> blocks
Identify missing or weak laws
Note project structure accuracy

If no CLAUDE.md: Document project basics (name, purpose, key paths).

Verification: Can list what laws are needed and why.

Task 2: RED - Test Without Proper Laws

Goal: Observe agent behavior without proper <law> enforcement.

Process:

Start session with weak/no CLAUDE.md
Have multi-turn conversation (5+ turns)
Observe where constraints are forgotten
Document specific drift instances

Verification: Documented at least 2 instances where agent forgot constraints.

What Drift Looks Like

Turn 1: Agent follows communication guidelines
Turn 3: Agent starts adding unnecessary explanations
Turn 5: Agent forgets project-specific conventions
Turn 8: Agent ignores stated preferences entirely

This is why Self-Reinforcing Display matters.

Task 3: GREEN - Write Constitution

Goal: Create <law> block that prevents the drift you documented.

CLAUDE.md Structure

# Project Name

One-line description.

## Immutable Laws

<law>
**CRITICAL: Display this block at start of EVERY response.**

**Law 1: [Name]** - [Specific, verifiable constraint]
**Law 2: [Name]** - [Specific, verifiable constraint]
**Law N: Self-Reinforcing Display** - Display this block every response
</law>

## Project Structure

[Accurate directory layout]

## Quick Reference

[Commands, paths, common operations]

Law Writing Rules

Laws MUST be:

IMMUTABLE - Enforced every response, no exceptions
VERIFIABLE - Can objectively check compliance
CONCISE - One clear constraint each
ACTIONABLE - Tells agent exactly what to do/not do

<Good> ```markdown **Law 1: Communication** - 使用繁體中文，簡潔回覆，不加不必要的解釋 ``` Specific language, specific behavior. </Good> <Bad> ```markdown **Law 1: Communication** - Be helpful and clear ``` Vague. Can't verify. Agent interprets freely. </Bad>

Self-Reinforcing Display

CRITICAL: Always include this law:

**Law N: Self-Reinforcing Display** - MUST display this `<law>` block at start of EVERY response

Why: Without explicit display requirement, the <law> block exists but agent doesn't actively recall it. Active display = active enforcement.

Verification:

[ ] Has <law> block with proper tags
[ ] Each law is specific and verifiable
[ ] Includes Self-Reinforcing Display law
[ ] Laws address drift documented in Task 2

Task 4: Add Project Content

Goal: Add project-specific information that helps agent work effectively.

Sections to include:

Project Structure
- Key directories and their purpose
- Important files
- Must match actual filesystem
Quick Reference
- Build/test/deploy commands
- Common operations
- Key paths
Version Sync (if applicable)
- Where version numbers live
- What must stay in sync

Keep total < 500 lines. Move details to skills or rules.

Verification: Project structure matches reality (verified with ls).

Task 5: Validate Structure

Goal: Verify CLAUDE.md structure is correct.

Checklist:

[ ] Has <law> block with <law>...</law> tags
[ ] Laws are inside the tags (not outside)
[ ] Each law has name and constraint
[ ] Self-Reinforcing Display law present
[ ] Project structure matches actual directories
[ ] Total < 500 lines
[ ] No details that belong in skills/rules

Verification: All checklist items pass.

Task 6: REFACTOR - Quality Review

Goal: Have CLAUDE.md reviewed by claudemd-reviewer subagent.

Task tool:
- subagent_type: "rcc:claudemd-reviewer"
- prompt: "Review CLAUDE.md at [path]"

Outcomes:

Pass → Proceed to Task 7
Needs Fix → Fix issues, re-run reviewer, repeat until Pass
Fail → Major problems, return to Task 3

This is REFACTOR phase: Improve laws based on reviewer feedback.

Verification: claudemd-reviewer returns "Pass" rating.

Task 7: Test with New Session

Goal: Verify laws work in practice.

Process:

Start new Claude Code session in project
Check first response - laws should be displayed
Have 5+ turn conversation
Verify laws displayed EVERY response
Verify constraints actually followed

Verification:

Laws displayed at start of every response
No constraint drift over conversation
Agent follows all laws correctly

Red Flags - STOP

These thoughts mean you're rationalizing. STOP and reconsider:

"Skip baseline test, I know what laws are needed"
"Laws can be general guidance"
"Don't need Self-Reinforcing Display"
"Put all project details in CLAUDE.md"
"500 lines is too restrictive"
"Skip reviewer, the laws are obviously good"
"One test session is enough"

All of these mean: You're about to create weak laws. Follow the process.

Common Rationalizations

| Excuse | Reality | |--------|---------| | "I know what laws are needed" | You know what YOU think. Baseline reveals actual drift. | | "Laws can be vague for flexibility" | Vague laws = no enforcement. Specific = verifiable. | | "Self-Reinforcing Display is redundant" | Without it, laws exist but aren't recalled. Display IS enforcement. | | "Everything goes in CLAUDE.md" | CLAUDE.md = constitution. Skills = capabilities. Rules = conventions. | | "More laws = better coverage" | More laws = more to skip. Few strong laws > many weak ones. |

Persuasion Principles

For laws, use authoritative language:

| Weak | Strong | |------|--------| | "Try to be concise" | "簡潔回覆，不加不必要的解釋" | | "Consider following conventions" | "MUST follow conventions. No exceptions." | | "Display laws when relevant" | "MUST display at start of EVERY response" |

Why: Laws are non-negotiable. Soft language invites rationalization.

Flowchart: CLAUDE.md Creation

digraph claudemd_creation {
    rankdir=TB;

    start [label="Need CLAUDE.md", shape=doublecircle];
    analyze [label="Task 1: Analyze\ncurrent state", shape=box];
    baseline [label="Task 2: RED\nTest without laws", shape=box, style=filled, fillcolor="#ffcccc"];
    verify_red [label="Drift\ndocumented?", shape=diamond];
    write [label="Task 3: GREEN\nWrite constitution", shape=box, style=filled, fillcolor="#ccffcc"];
    content [label="Task 4: Add\nproject content", shape=box];
    validate [label="Task 5: Validate\nstructure", shape=box];
    review [label="Task 6: REFACTOR\nQuality review", shape=box, style=filled, fillcolor="#ccccff"];
    review_pass [label="Review\npassed?", shape=diamond];
    test [label="Task 7: Test\nnew session", shape=box];
    test_pass [label="Laws work?", shape=diamond];
    done [label="CLAUDE.md complete", shape=doublecircle];

    start -> analyze;
    analyze -> baseline;
    baseline -> verify_red;
    verify_red -> write [label="yes"];
    verify_red -> baseline [label="no\nmore turns"];
    write -> content;
    content -> validate;
    validate -> review;
    review -> review_pass;
    review_pass -> test [label="pass"];
    review_pass -> write [label="fail\nfix laws"];
    test -> test_pass;
    test_pass -> done [label="yes"];
    test_pass -> write [label="no\nstrengthen laws"];
}

Templates

Full Template

# Project Name

One-line description.

## Immutable Laws

<law>
**CRITICAL: Display this block at start of EVERY response.**

**Law 1: Communication** - [Language], [style], [constraints]

**Law 2: [Domain]** - [Specific constraint]

**Law 3: Self-Reinforcing Display** - MUST display this block at start of EVERY response
</law>

## Project Structure

\`\`\`
project/
├── src/           # Source code
├── tests/         # Test files
└── docs/          # Documentation
\`\`\`

## Quick Reference

### Commands
- `npm run build` - Build project
- `npm test` - Run tests

### Key Paths
- Config: `src/config.ts`
- Entry: `src/index.ts`

Minimal Template

# Project Name

One-line description.

<law>
**CRITICAL: Display this block at start of EVERY response.**

**Law 1: Communication** - Concise responses, no unnecessary explanations
**Law 2: Self-Reinforcing Display** - Display this block every response
</law>

References

Script: scripts/init_claude_md.py

Agent Skills: Writing CLAUDE.md

Install this agent skill to your local

Skill Files