[FEATURE] CLAUDE.md enforcement

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Current Behavior

• A project may have a well-documented CLAUDE.md file with:
• Known issues and their solutions
• Project-specific constraints
• Critical reminders about common mistakes
• Specific command syntax and workflows
• Claude Code does not automatically read or follow these instructions
• Users must manually tell Claude to read CLAUDE.md, or the constraints are ignored
• This results in repeated mistakes that are already documented and solved

Proposed Solution

Expected Behavior

• Claude Code should detect the presence of CLAUDE.md at session start
• The file should be automatically read and understood
• All constraints, known issues, and documented solutions should be applied throughout the session
• Work should be validated against these documented constraints before committing

Alternative Solutions

Repeated usage burning through my weekly allotment

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

Example from Actual Project

An ebook project had documented the following issues in CLAUDE.md:

1. PDF Generation Flag Issue (documented in v1.12, ~commit ddbc7d0)

• Problem: Using pandoc --toc flag causes TOC to appear before cover page
• Solution: Remove --toc flag, use manual \tableofcontents instead
• Status: Fixed in v1.12 but documentation wasn't clear
• Result: User encountered same issue in v1.16, wasted significant tokens on repeated fix

1. Cover Page Formatting (7+ occurrences)

• Problem: TOC appearing on cover page due to incorrect \newpage placement
• Solution: Specific LaTeX structure documented in CLAUDE.md
• Result: Had to be fixed multiple times across sessions

1. Page Numbering (multiple occurrences)

• Problem: TOC has roman numerals, content has arabic numerals (correct), but partnership pages need \thispagestyle{empty}
• Solution: Documented in CLAUDE.md
• Result: User had to re-explain the solution multiple times

Cost to User

• Tokens wasted: Hundreds of tokens regenerating PDFs for the same documented issue
• Subscription time: Days of monthly allocation spent on repeated problems
• User frustration: Having to explain and re-fix the same issue multiple times

Additional Context

Bug Report: CLAUDE.md Files Not Triggering Project Initialization

Summary

When a CLAUDE.md file exists in a project repository, Claude Code should automatically read and apply those project-specific instructions at the start of each session. Currently, this does not happen, causing users to waste tokens and subscription time on repeated mistakes that are already documented in CLAUDE.md.

Problem Description

Current Behavior

• A project may have a well-documented CLAUDE.md file with:
• Known issues and their solutions
• Project-specific constraints
• Critical reminders about common mistakes
• Specific command syntax and workflows
• Claude Code does not automatically read or follow these instructions
• Users must manually tell Claude to read CLAUDE.md, or the constraints are ignored
• This results in repeated mistakes that are already documented and solved

Expected Behavior

• Claude Code should detect the presence of CLAUDE.md at session start
• The file should be automatically read and understood
• All constraints, known issues, and documented solutions should be applied throughout the session
• Work should be validated against these documented constraints before committing

Real-World Impact

Example from Actual Project

An ebook project had documented the following issues in CLAUDE.md:

1. PDF Generation Flag Issue (documented in v1.12, ~commit ddbc7d0)

• Problem: Using pandoc --toc flag causes TOC to appear before cover page
• Solution: Remove --toc flag, use manual \tableofcontents instead
• Status: Fixed in v1.12 but documentation wasn't clear
• Result: User encountered same issue in v1.16, wasted significant tokens on repeated fix

1. Cover Page Formatting (7+ occurrences)

• Problem: TOC appearing on cover page due to incorrect \newpage placement
• Solution: Specific LaTeX structure documented in CLAUDE.md
• Result: Had to be fixed multiple times across sessions

1. Page Numbering (multiple occurrences)

• Problem: TOC has roman numerals, content has arabic numerals (correct), but partnership pages need \thispagestyle{empty}
• Solution: Documented in CLAUDE.md
• Result: User had to re-explain the solution multiple times

Cost to User

• Tokens wasted: Hundreds of tokens regenerating PDFs for the same documented issue
• Subscription time: Days of monthly allocation spent on repeated problems
• User frustration: Having to explain and re-fix the same issue multiple times

Root Cause Analysis

1. Claude Code treats CLAUDE.md as optional reference material
2. There is no automatic session initialization when CLAUDE.md is detected
3. No enforcement mechanism to validate work against documented constraints
4. No explicit check to read project documentation at start of session

Proposed Solution

Implement automatic project initialization when CLAUDE.md is detected:

1. At session start: Automatically read CLAUDE.md if it exists in the working directory
2. Parse and understand: Extract:

• Project overview
• Key constraints
• Known issues and their solutions
• Critical reminders (marked with 🚨 or similar)
• Specific command syntax

1. Apply constraints: Use this information to guide decision-making throughout the session
2. Validation: Before significant operations (like PDF generation), validate against documented constraints
3. Acknowledgment: Tell the user that CLAUDE.md was read and understood

Example Implementation

At session start, Claude Code should behave like:

[Session Start]
✓ Detected CLAUDE.md in project directory
✓ Reading project constraints and known issues...
✓ Found 3 critical reminders and 2 documented solutions
✓ Project: "Cigar Ebook" - Tales from the Cigar Lounge
✓ Key constraints applied:
  - PDF generation: NO --toc flag (use manual \tableofcontents)
  - Cover page: MUST appear first (specific LaTeX structure required)
  - Page numbering: Partnership pages need \thispagestyle{empty}
✓ Ready to work with full project context

Files Involved

• Project: ebook project (private GitHub repo)
• CLAUDE.md: Contains all project-specific guidance
• Impact: All users with CLAUDE.md files in their projects

Severity

High - This affects productivity and cost for any long-term project using CLAUDE.md

Additional Notes

This issue becomes more critical as:

• Projects get larger and more complex
• More constraints and known issues accumulate
• Users work on projects across multiple sessions
• Token budgets are finite and costly

The presence of CLAUDE.md should be treated as a signal that the user cares deeply about consistency and wants Claude to follow specific guidelines. Currently, that signal is ignored.