self-maintaining-claude-md

name	self-maintaining-claude-md
description	Use when starting any task in a project - keeps CLAUDE.md instruction file current with high-level project state, prompts for init if missing, adds reflection todo before work to ensure documentation stays updated

Self-Maintaining CLAUDE.md

Overview

CLAUDE.md is your project's instruction file for Claude. It must stay current with the project's high-level state.

Core principle: Before starting implementation, check if you created the "Reflect on changes and update CLAUDE.md" todo. If not, create it now — then start working.

Mandatory Workflow

1. Check CLAUDE.md Exists

Before ANY task, check if CLAUDE.md exists in the project root.

If missing:

• STOP
• Prompt user: "No CLAUDE.md found. Please run the init command to create it."
• DO NOT create it yourself
• DO NOT continue without it

Why: User-initialized CLAUDE.md ensures proper setup and user preferences.

2. Add Reflection Todo BEFORE Work

Before starting any implementation task, check if you created the "Reflect on changes and update CLAUDE.md" todo. If not, create it now at the END of your todo list — then start working.

Why at the end: It runs AFTER all implementation work completes, so you update documentation based on actual changes.

Why before starting: "Later" means "forgotten". Adding the todo takes 10 seconds. Forgetting to update CLAUDE.md wastes hours of future work.

3. Process Reflection Todo

When processing the reflection todo, maintaining CLAUDE.md means ADD, UPDATE, or REMOVE content as needed.

Three types of maintenance:

1. ADD - New high-level information that didn't exist before
2. - Modify existing content that has changed