claude-md-writer（Claude MD 写作）

CLAUDE.md Writer

A skill for creating and optimizing CLAUDE.md files following official Anthropic best practices.

Golden Rule

Para cada linea, pregunta: *"Eliminar esto causaria que Claude cometa errores?"* Si no, eliminalo. CLAUDE.md inflados causan que Claude ignore instrucciones.

"Think of CLAUDE.md as the 'unwritten knowledge' in your codebase"

Quick Tools

• /init - Genera CLAUDE.md inicial basado en la estructura del proyecto
• # key - Agregar instrucciones dinamicamente durante la sesion

@import Syntax

CLAUDE.md puede importar otros archivos:

See @README.md for overview and @package.json for commands.
Git workflow: @docs/git-instructions.md

Reference Documentation

For examples and validation checklist, see:

• references/good-example.md - Well-structured CLAUDE.md example
• references/bad-example.md - Common anti-patterns to avoid
• references/checklist.md - Quality validation checklist
• references/dead-weight-audit.md - Dead weight audit (5 criterios para recortar instrucciones)

What to Include vs Exclude

CLAUDE.md vs Skills

Content Triage

Antes de agregar contenido a CLAUDE.md, evaluar:

Si el usuario quiere agregar info condicional ("Cuando trabajes con X...", "Para tareas de tipo Y..."), sugerir crear un skill separado.

Usage Modes

Process

Step 1: Analyze the Project

Identify tech stack, project structure, and existing documentation.

Step 2: Apply the Three Dimensions

Step 3: Write Following Best Practices

Length: Keep under 200 lines (ideal ~100 lines)

Structure (in order):

1. Repository Overview (1 paragraph)
2. Why This Exists (purpose, users)
3. Quick Start & Commands (bash with descriptions)
4. Architecture Overview (key patterns)
5. Key Development Rules (with emphasis)
6. References (links to detailed docs)

Emphasis for Critical Rules:

- **CRITICAL**: [Never violate this]
- **IMPORTANT**: [Always do this]

Progressive Disclosure:

• Use file references instead of code snippets
• Link to external docs for detailed topics
• Keep CLAUDE.md focused on universal instructions

Step 4: Verify with Checklist

Before finalizing, run through the checklist in references/checklist.md.

Template

# CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

## Repository Overview

[One paragraph: what this project is, tech stack, main purpose]

## Why This Exists

[What problem it solves, who uses it, business context]

## Quick Start & Commands

\`\`\`bash
npm ci        # Install dependencies
npm start     # Start dev server
npm test      # Run tests
npm run build # Production build
\`\`\`

## Architecture Overview

[Key patterns, folder structure, main concepts - keep brief]

## Key Development Rules

- **CRITICAL**: [Most important rule that must never be violated]
- **IMPORTANT**: [Second most important rule]

## References

- `/docs/` - Detailed documentation
- `README.md` - Project readme

Dead Weight Audit

Cuando el usuario pida auditar su setup, aplicar los 5 criterios de references/dead-weight-audit.md contra cada regla:

1. ¿Default? — Claude ya lo hace sin que se lo digan
2. ¿Conflicto? — Contradice otra regla en el setup
3. ¿Redundancia? — Cubierto por otra regla o proceso
4. ¿Parche puntual? — Agregado para arreglar un output malo específico
5. ¿Vago? — Se interpreta distinto cada vez

Output esperado:

• Lista de cortes con razón en una línea cada uno
• Lista de conflictos encontrados entre archivos
• Versión limpia del CLAUDE.md sin dead weight

Proceso post-audit: eliminar → probar 3 tareas típicas → re-agregar solo lo que se rompió.

Anti-Patterns to Avoid