dev-claude-md

CLAUDE.md Generation and Maintenance

Why This Matters

CLAUDE.md is a markdown file that lives in the root of your development folder. When you use Claude Code, it automatically reads this file and follows the rules in any conversation. Think of it as instructions that shape how AI behaves throughout your entire coding project.

This file does not stay static. It evolves through many changes during development. It starts as a basic document with tech stack information and grows into a comprehensive set of rules covering everything from source-of-truth hierarchy to specific warnings about outdated approaches.

Interaction Method

If AskUserQuestion is available, use it for all prompts below.

If not, present each question as a numbered list and wait for a reply before proceeding. For multiSelect questions, accept comma-separated numbers (e.g. 1, 3). Never skip or auto-answer without explicit user consent.

---

Step 0: Before starting

1. Announce your execution plan: Before doing anything, state what you will do in this activity: "Here's what I'm going to do: 1) gather your project context – what documents, tech stack, and code you have, 2) define the source hierarchy for AI decision-making, 3) generate a customized CLAUDE.md file, 4) explain how to maintain it over time." This is a commitment device – harder to skip steps you just announced.

2. Conditional teaching: Ask the user if they are familiar with what CLAUDE.md is and how it shapes AI behavior in their project. If yes, give a one-sentence refresher. If no, explain it in simple terms: it's a markdown file at the root of your project that Claude Code reads automatically – think of it as persistent instructions that shape how AI behaves throughout your entire codebase.

   Required: ALWAYS ask the question, ALWAYS give the refresher when the user says yes. Never skip this step because the user "is a designer" or "already demonstrated familiarity earlier." Users want a memory refresh on every activity, including ones they know. Phrases like "I'll skip the explainer (you're a designer)" are forbidden — they signal the model has decided ON BEHALF OF the user that a refresher isn't needed. The user, not the model, decides what's redundant. The refresher takes one sentence; the cost is trivial; the value to a tired user mid-session is high.