vibe-scaffold

A high-performance project template for Claude Code, implementing the principles from The Architect's Guide to Agentic Vibe Coding.

What This Is

A ready-to-clone scaffold that gives you:

• Context Architecture — Layered CLAUDE.md files that keep Claude oriented without bloating context
• Deny-by-Default Permissions — Sensitive operations blocked until explicitly allowed
• Multi-Layered Memory — Enterprise → user → project → local settings hierarchy
• MCP Integration — Pre-configured Model Context Protocol examples for common servers
• Subagent Patterns — Actor and Evaluator agents for code review, security, testing
• Workflow Automation — Explore → Plan → Code → Commit cycle with quality gates

Quick Start

# Clone the scaffold
git clone <your-fork-url> my-project
cd my-project

# Run interactive setup
./scripts/setup.sh

# Start working with Claude Code
claude

The setup script will:

1. Check prerequisites (claude, jq, git)
2. Copy .example files to their real locations
3. Install git hooks
4. Print next steps

Project Structure

.
├── CLAUDE.md                    # Project memory (edit this for your project)
├── CLAUDE.local.md.example      # Template for personal overrides
├── .claude/
│   ├── settings.json            # Deny-by-default permissions + hooks
│   ├── agents/                  # Subagent definitions
│   ├── skills/                  # Reusable skill workflows
│   └── commands/                # Slash commands
├── .mcp.json                    # Team MCP config (committed)
├── .mcp.local.json.example      # Personal MCP config (gitignored)
├── examples/                    # Reference configs for all features
├── scripts/                     # Setup, hooks, and workflow helpers
└── docs/                        # Guides for each system

Configuration Layers

Claude Code loads configuration in a specific order, with later layers overriding earlier ones:

Layer	File	Scope	Committed?
Enterprise	/etc/claude-code/CLAUDE.md	All users on machine	N/A
User	~/.claude/CLAUDE.md	All your projects	No
Project	./CLAUDE.md	This project	Yes
Local	./CLAUDE.local.md	Your personal overrides	No

See docs/memory-hierarchy.md for details.

Permissions Model

The scaffold ships with deny-by-default permissions. Sensitive operations (writing .env, pushing to main, deleting files) are blocked. Safe operations (reading files, running tests, linting) are allowed.

See docs/permission-strategy.md for the full policy.

Subagents

Four pre-built agents in .claude/agents/:

Agent	Pattern	Purpose
code-reviewer	Actor	Reviews code for quality, style, and correctness
security-reviewer	Actor	Checks for OWASP top 10 and security issues
test-writer	Actor	Generates tests matching project conventions
evaluator	Evaluator	Attempts to break code by finding edge cases

See docs/subagent-patterns.md for usage.

Skills

Three reusable skills in .claude/skills/:

• pr-check — Review PRs against a customizable checklist
• gen-test — Generate unit and integration tests
• explore-plan-code — Full Explore → Plan → Code → Commit workflow

MCP Servers

Example configurations for common MCP servers in examples/mcp/:

• GitHub (HTTP-based)
• Filesystem (stdio-based)
• Web Fetch
• PostgreSQL Database
• Multi-server combined setup

See docs/mcp-guide.md for setup instructions.

Workflow

The recommended workflow follows four phases:

1. Explore — Understand the codebase before changing it
2. Plan — Design the approach, get approval
3. Code — Implement with quality gates
4. Commit — Conventional commits with verification

See docs/workflow-guide.md for the full guide.

Customizing for Your Project

1. Edit CLAUDE.md to describe your project's architecture, conventions, and rules
2. Adjust .claude/settings.json permissions for your tech stack
3. Configure .mcp.json for your team's MCP servers
4. Modify subagents and skills to match your workflow
5. Update git hooks for your language/framework

License

MIT — see LICENSE.