claude-md-architect

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: claude-md-architect
description: "CLAUDE.md file generation and optimization for Claude Code projects. Capabilities: initialize project instructions, analyze codebase context, optimize existing CLAUDE.md, apply Anthropic best practices, reduce token usage, improve effectiveness. Actions: init, create, optimize, enhance CLAUDE.md files. Keywords: CLAUDE.md, project instructions, Claude Code setup, project context, codebase analysis, Anthropic best practices, token optimization, project configuration, AI instructions, coding guidelines, project rules, workspace setup. Use when: initializing CLAUDE.md for new projects, optimizing existing project instructions, setting up Claude Code for a codebase, improving AI coding guidelines."
---

# CLAUDE.md Architect Skill

Generate and optimize CLAUDE.md files for software projects by analyzing codebase context and applying Anthropic engineering best practices. Creates concise, maintainable project instructions that maximize Claude Code effectiveness while minimizing token consumption.

## Core Principles

1. **Conciseness over Completeness**: Treat CLAUDE.md like frequently-used prompts, not exhaustive documentation
2. **Evidence-Based Context**: Analyze actual codebase before making recommendations
3. **Incremental Refinement**: Start minimal, iterate based on effectiveness
4. **Token Efficiency**: Every line should earn its presence in the context window
5. **Human-Readable Structure**: Use clear organization with XML tags for parsing

## When to Use This Skill

Activate when user requests:
- "init CLAUDE.md" or "create project instructions"
- "optimize" or "improve" existing CLAUDE.md
- "setup Claude for my project"
- Project-specific instructions for Claude Code
- Starting work on a new project that needs documentation
- Existing CLAUDE.md is outdated or ineffective

## Quick Decision Tree

```
User Request
    │
    ├─→ "init" or "create" → Initialize New CLAUDE.md
    │   └─→ Follow: @refs/initialization-workflow.md
    │
    ├─→ "optimize" or "improve" → Optimize Existing CLAUDE.md
    │   └─→ Follow: @refs/optimization-patterns.md
    │
    └─→ "integrate" or "setup MCP/slash commands" → Integration
        └─→ Follow: @refs/integration-strategies.md
```

## Workflow Overview

### Initialize New CLAUDE.md

**Quick Steps:**
1. **Discover** - Analyze codebase (language, framework, structure, tests)
2. **Extract** - Identify code style, commands, patterns
3. **Generate** - Select template, customize for project
4. **Validate** - Verify commands, check token count
5. **Present** - Show output with explanation

**Detailed Instructions:** @refs/initialization-workflow.md

### Optimize Existing CLAUDE.md

**Quick Steps:**
1. **Analyze** - Evaluate token efficiency, accuracy, relevance
2. **Identify** - Find redundancy, outdated info, generic fluff
3. **Refactor** - Apply token reduction, restructure, improve clarity
4. **Test** - Verify 40%+ token reduction, retain critical info
5. **Present** - Show before/after with metrics

**Detailed Instructions:** @refs/optimization-patterns.md

## Token Reduction Quick Reference

### Before (Verbose)
```markdown
When you are implementing new features in this codebase, it's very important that you always make sure to write comprehensive tests for all the functionality you add. We use Jest as our testing framework, and we expect all new code to have at least 80% code coverage.
```

### After (Concise)
```markdown
### Testing Requirements
- New features require tests (Jest, >80% coverage)
- Unit tests: Individual functions in `src/lib/`
- Integration tests: API endpoints with Supertest
```

**Result:** 70% token reduction, same information

## Template Selection Guide

| Project Type | Key Indicators | Template Focus |
|--------------|----------------|----------------|
| **Web App** | React/Vue/Angular, frontend build | UI components, responsive design, routing |
| **Backend API** | Express/FastAPI, database, auth | RESTful conventions, va