Meta-documentation framework for effective development with Claude Code and AI agents

⚠️ Important Note: This framework is designed for beginners practicing vibe-coding, not professional developers. It covers a tiny fraction of AI coding agents' capabilities and will evolve and be modified as practical experience accumulates.

🎓 Created to support students of the AI Agents course for beginners:

• Full course: AI Agents Full Course (Russian)
• For complete beginners: Free AI Intro Course (Russian)

🇷🇺 Русская версия: README_RU.md

📁 Шаблоны доступны на двух языках:

• Init/ — русские шаблоны (Russian templates)
• init_eng/ — английские шаблоны (English templates)

Claude Code Starter is a ready-to-use meta-documentation framework that transforms chaotic AI-assisted development into a structured and efficient process.

When working with Claude Code or other AI agents:

• 🔥 AI doesn't understand project context → makes wrong architectural decisions
• 💸 Loads entire project into context → wastes tokens and money
• 🔄 You explain the same things repeatedly → waste time
• 🎲 Unpredictable results → no single source of truth
• 🚫 Security issues → AI doesn't know the rules

The framework provides 11 ready-made documentation templates that:

• ✅ Auto-load into Claude Code context (via CLAUDE.md)
• ✅ Save tokens through modular architecture
• ✅ Single source of truth for AI and team
• ✅ Built-in security (SECURITY.md)
• ✅ Slash commands for automation (/commit, /pr, /migrate, etc.)
• ✅ Standardized processes via Makefile

git clone https://github.com/alexeykrol/claude-code-starter.git
cd claude-code-starter

# Create new project or navigate to existing one
mkdir my-new-project
cd my-new-project

# Copy all files from Init/
cp -r ../claude-code-starter/Init/* .
cp -r ../claude-code-starter/Init/.claude .

This is the most important file - start here:

# Open in editor
code PROJECT_INTAKE.md

# Or use Claude Code
claude PROJECT_INTAKE.md

Fill in key sections:

1. Problem → Solution → Value - why does your project exist?
2. User Personas - who are your users?
3. User Flows - how will they interact?
4. Unique vs Standard Features - what to build vs what to integrate?
5. Modular Structure - how to break into modules?

# In your project root
claude

# Claude will automatically load CLAUDE.md into context
# And read all necessary files

"Read PROJECT_INTAKE.md and ask all clarifying questions"

Monolithic approach problem:

Claude loads entire project (5000 lines) →
Wastes tokens reading everything →
Expensive and slow →
May get confused in large context

Solution through modules:

Claude loads only needed module (200 lines) →
Fewer tokens →
Faster and cheaper →
Better understanding of task

Application = Set of small LEGO blocks

Each module:

• Solves one narrow task
• Has clear input and output
• Can be tested separately
• Doesn't depend on other modules

Read more in Init/ARCHITECTURE.md (section "Module Architecture")

1. Copy templates from Init/ to your project
2. Fill PROJECT_INTAKE.md - this is the foundation
3. Read SECURITY.md - internalize security rules
4. Configure Makefile for your stack (React/Vue/Node/etc)

1. Launch claude in project root
2. CLAUDE.md auto-loads into context
3. Ask AI to read PROJECT_INTAKE.md and ask questions
4. Work modularly: one module → testing → next module

1. Update BACKLOG.md after each sprint
2. Enhance ARCHITECTURE.md with architectural decisions
3. Expand AGENTS.md with new patterns
4. Use slash commands to automate routine tasks

✅ DO:

• Start with "WHY?" - problem → solution → value
• Create 2-3 User Personas with names and pain points
• Describe User Flows step-by-step (not abstractions!)
• Separate features into unique (build) vs standard (integrate ready-made)
• Plan modular structure

❌ DON'T:

• Leave [FILL IN] without filling
• Write abstractly without specifics
• Plan to build standard features from scratch (Auth, Payments, etc)

✅ DO:

• Use /commit instead of manual commits
• Load context via TodoWrite for task tracking
• Work by modules: Auth → API → Screens → Business Logic
• Ask AI to update documentation with changes

❌ DON'T:

• Don't load entire project into context at once
• Don't skip SECURITY.md
• Don't ignore architectural decisions from ARCHITECTURE.md

✅ ALWAYS:

• Read SECURITY.md before coding
• Use .env.example → .env.local
• Validate all input data
• Use /security slash command for audits

❌ NEVER:

• Commit .env files
• Hardcode secrets in code
• Ignore security warnings

After copying templates, your project will look like this:

your-project/
├── .claude/
│   ├── commands/           # Slash commands (/commit, /pr, etc)
│   └── settings.json       # Claude Code access permissions
│
├── src/                    # Your code
│   ├── features/           # Feature modules
│   ├── lib/               # Utilities and services
│   └── ...
│
├── CLAUDE.md              # 🤖 Auto-loads in Claude Code
├── PROJECT_INTAKE.md      # ⭐ Project requirements
├── SECURITY.md            # 🔐 Security rules
├── ARCHITECTURE.md        # 🏗️ Architectural decisions
├── BACKLOG.md            # 📋 Implementation status
├── AGENTS.md             # 🎯 AI instructions
├── WORKFLOW.md           # 🔄 Development processes
├── Makefile              # 🛠️ Standard commands
├── .env.example          # 🔒 Variables template
└── README.md             # 📖 Project documentation (from README-TEMPLATE.md)

The framework is alive and evolving. To get updates:

# In claude-code-starter folder
git pull origin main

# Compare changes and update your projects manually
diff Init/CLAUDE.md your-project/CLAUDE.md

Recommendation: Don't overwrite your filled files - copy only new sections.

The framework is created for the community and open to improvements!

1. Fork the repository
2. Create feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open Pull Request

• 📝 New sections in templates
• 🔧 New slash commands
• 🎨 Examples for popular stacks (Next.js, Vue, etc)
• 🌍 Translations (already have Russian version!)
• 📖 Tutorials and use cases

• Claude Code Documentation - official documentation
• GitHub Repository - framework source code
• Issues - report problem or suggest improvement

MIT License - use freely in your projects!

Framework inspired by:

• Official Claude Code best practices
• Experience developing with AI agents
• Modular architecture principles
• Developer community

• ✅ Basic documentation templates
• ✅ Slash commands for git and security
• ✅ Makefile for standardization
• ✅ Modular architecture

• Examples for Next.js
• Examples for Vue 3
• English version
• Video tutorials

• CLI for automatic initialization
• Integration with popular templates
• VS Code plugins
• AI-powered code review templates

If something is unclear:

1. Read Init/PROJECT_INTAKE.md - detailed comments there
2. Study Init/CLAUDE.md - Quick Start there
3. Open Issue

Happy coding with Claude! 🤖✨

This framework turns AI-assisted development from chaos into a structured process.