A modular, level-based project template for teams building software with Claude Code, Obsidian, and Figma.
Pick your maturity level. Plug in your specs. Ship.
Every team reinvents project structure from scratch. This blueprint gives you an opinionated skeleton that scales from solo MVP to autonomous multi-agent systems â without locking you into a specific stack.
Level 1 â You and Claude as copilot on a weekend project
Level 4 â Agent teams with self-healing CI and compliance auditors
| Level | What | Who it's for | What you get |
|---|---|---|---|
| L1 | ReAct loop | Solo devs, MVPs | CLAUDE.md + docs structure + Obsidian vault |
| L2 | Planner + Executor | Small teams | + Skills (auto-invoked knowledge) + Slash commands |
| L3 | Multi-agent with critique | Teams in production | + Hooks (automated gates) + Spec review pipeline |
| L4 | Autonomous system | Mature teams | + Specialized agents + Agent teams + Self-healing |
Each level includes everything from the levels below it.
Where do these levels come from? This framework is a practical synthesis â not invented from scratch. It combines industry frameworks, published research, and hands-on experience building with these tools. See Influences & Attribution for the full picture.
# Clone
git clone https://github.com/rtazima/claude-proj-blueprint.git my-project
cd my-project
# Remove the template's git history and start fresh
rm -rf .git && git init
# Bootstrap at your level
chmod +x scripts/bootstrap.sh
./scripts/bootstrap.sh --level 2
# Fill in your project specifics
grep -r '\[SPEC\]' CLAUDE.md docs/ .claude/ | head -20
# Open docs/ as an Obsidian vault (optional but recommended)
# In Obsidian: Open folder as vault â select docs/
# Start working
claudeyour-project/
âââ CLAUDE.md â L1+ Hub â Claude reads this first
âââ .claude/
â âââ settings.json â L1+ Permissions & safety
â âââ output-styles/ â L2+ Communication style presets (direct, verbose)
â âââ skills/ â L2+ Auto-invoked knowledge packs (18 skills)
â â âââ implement-prd/ â Implement from PRD
â â âââ prd-writer/ â Draft/refine PRDs from rough ideas
â â âââ debugger/ â Systematic debugging workflow
â â âââ testing/ â Test generation and coverage
â â âââ refactor/ â Safe structural refactoring
â â âââ code-review/ â Review checklist
â â âââ api-designer/ â API contract design
â â âââ migration/ â L3 Database migration workflow
â â âââ tech-debt/ â L3 Debt identification and tracking
â â âââ frontend-agent/ â UI generation without Figma
â â âââ persistence/ â Ralph mode â iterate until done
â â âââ slop-cleaner/ â Remove AI-generated code noise
â â âââ learner/ â L4 Extract patterns to improve skills
â â âââ adr/ â Architecture Decision Records
â â âââ intent-markers/ â :PERF:/:UNSAFE:/:SCHEMA: code annotations
â â âââ incoherence-detector/ â Spec vs docs vs code mismatch finder
â â âââ memory/ â L4 Long-term memory retrieval
â â âââ _template-skill/ â Create your own
â âââ commands/ â L2+ Slash commands (10 commands)
â â âââ implement.md â /implement <prd-path>
â â âââ ralph.md â /ralph <prd-path> (don't stop)
â â âââ debug.md â /debug <error|file>
â â âââ refactor.md â /refactor <file|module>
â â âââ clean.md â /clean [file|dir]
â â âââ debt.md â /debt [dir]
â â âââ learn.md â /learn [--commits N]
â â âââ deploy.md â /deploy
â â âââ spec-review.md â /spec-review <path>
â â âââ memory.md â /memory <search|index|stats>
â âââ hooks.json â L3+ Automated gates (8 hooks)
â âââ agents/ â L4+ Specialized sub-agents (4 agents)
â âââ security-auditor.md â OWASP, injection, auth (opus)
â âââ compliance-auditor.md â LGPD, GDPR, HIPAA, PCI-DSS (opus)
â âââ quality-guardian.md â Tests, docs, Definition of Done (sonnet)
â âââ performance-auditor.md â N+1, caching, pagination (sonnet)
âââ docs/ â L1+ Obsidian vault
â âââ product/ â PRDs, vision, roadmap
â âââ architecture/ â ADRs (decision records)
â âââ specs/ â Modular spec modules
â â âââ conventions/ â Convention registry (role-phase mapping)
â â âââ documentation-standards.md â Token budgets, invisible knowledge test
â â âââ deliverables/ â L4 Agent output validation schemas
â âââ design-flow-guide.md â Figma vs Agent vs Hybrid decision
â âââ runbooks/ â Deploy, debug, post-mortems
âââ src/ â Your code
âââ memory/ â L4+ Long-term vector memory
â âââ index.py â Index project into vector DB
â âââ query.py â Semantic search CLI
â âââ config.yaml â Configuration
â âââ requirements.txt â pip install -r memory/requirements.txt
âââ logs/ â L4+ Agent event logs
â âââ agent-events.jsonl â JSONL event stream (gitignored)
âââ tools/ â L4+ Developer tools
â âââ agent-dashboard.html â Web dashboard for agent monitoring
âââ scripts/
âââ bootstrap.sh â Level-based setup
âââ lint-check.sh â L3+ post-write hook
âââ security-check.sh â L3+ pre-bash hook
âââ pre-commit-review.sh â L3+ AI code review on commit
âââ ai-review.sh â L3+ AI review (CLI or API)
âââ docs-check.sh â L3+ documentation sync warning
âââ magic-keywords.sh â L3+ auto-detect intent
âââ pre-compact-save.sh â L3+ save context before compaction
âââ context-guard.sh â L3+ warn on long conversations
âââ verify-deliverables.sh â L4 validate agent output
âââ post-commit-index.sh â L4 auto-index on commit
âââ agent-events.sh â L4 event protocol (JSONL emitter)
âââ agent-monitor.sh â L4 terminal dashboard (TUI)
Specs are plug-and-play knowledge modules in docs/specs/. Enable only what your project needs.
| Module | What it covers | When to enable |
|---|---|---|
compliance/ |
Laws, regulations, ISOs | Regulated data, certifications |
security/ |
OWASP, access control, crypto | Every production project |
observability/ |
Logs, metrics, traces, alerts | Every production project |
scalability/ |
Caching, queues, performance | When scale matters |
versioning/ |
API versions, migrations, semver | Public APIs, multiple clients |
design-system/ |
Design tokens, component patterns, UI strategy | Projects with UI â makes Figma optional |
accessibility/ |
WCAG, a11y | User-facing products |
i18n/ |
Multi-language, localization | International products |
testing-strategy/ |
Test pyramid, QA process | Teams with 3+ devs |
devops/ |
CI/CD, IaC, environments | Every production project |
api/ |
API conventions, endpoints, error format | Projects with APIs |
data-architecture/ |
Modeling, pipelines, analytics | Data-intensive products |
ai-ml/ |
Models, prompts, evals, guardrails | AI/ML products |
long-term-memory/ |
Vector DB, semantic search | L4 autonomous systems |
mkdir docs/specs/my-module
# Use any existing module as reference
# Optionally create .claude/skills/my-module/SKILL.md for auto-invocationEvery [SPEC] marker is an extension point. The blueprint tells you where things go; you fill in what goes there.
## Tech Stack
[SPEC] List the actual project stack:
- Backend: [linguagem + framework]Becomes:
## Tech Stack
- Backend: Python + FastAPI
- Frontend: React + TypeScript
- Database: PostgreSQLL1 â CLAUDE.md â Claude reads this automatically at every session. Your stack, architecture, conventions, gotchas. Keep it under 200 lines.
L2 â Skills â Markdown files that Claude loads based on natural language triggers. Say "write tests" and the testing skill activates. Say "debug this" and the debugger skill kicks in. 16 skills covering the full development lifecycle.
L3 â Hooks â Scripts that run before/after Claude uses tools. Lint on every file write. Security check before every bash command. Exit 0 = allow, exit 2 = block.
L4 â Agents â Sub-agents with their own context (security, compliance, quality, performance). Run individually or as a coordinated team with the author-critic loop.
L4 â Agent Monitor â Real-time observability for multi-agent sessions. Hooks emit structured JSONL events; two viewers consume them:
# Terminal dashboard (live, zero deps)
./scripts/agent-monitor.sh
# Web dashboard (visual graph + timeline)
python3 -m http.server 8080
# â http://localhost:8080/tools/agent-dashboard.htmlL4 â Memory â Vector database indexes docs/ and src/ for semantic search. Ask "how did we handle rate limiting?" and get the relevant ADR, code, and PRD. Supports Chroma (local, default) or pgvector (shared, team-wide).
pip install -r memory/requirements.txt
python memory/index.py # Index everything
python memory/query.py "auth" # Semantic search
python memory/query.py --stats # What's indexedcd your-project && claude
# L2+
# Shift+Tab+Tab â Plan Mode
# Describe feature intent
# Shift+Tab â Auto Accept
# /compact to compress context
# Commit frequently, new session per feature
# L2+ â Full lifecycle
# /ralph docs/product/feat-auth.md â iterate until all criteria pass
# /debug "TypeError in auth module" â systematic debugging
# /refactor src/auth/ â safe structural refactoring
# /clean src/ â remove AI slop from code
# /debt â scan and prioritize tech debt
# Or just say: "don't stop", "debug this", "refactor", "clean up"
# L3+
# /spec-review src/ â run 4-agent audit (security + compliance + quality + performance)
# Magic keywords work: "security audit", "tech debt", "migration", "design API"
# L4+
# /memory search "how did we handle rate limiting"
# /learn --commits 20 â extract patterns, improve skills
# "Create an agent team to implement auth with OAuth2"Obsidian â Open docs/ as a vault. PRDs, ADRs, specs are interconnected with [[wiki-links]].
Figma (optional) â For teams with a designer. Add Figma links to PRDs, use the Figma MCP server for design-to-code. See the Design Flow Guide to decide if you need it.
Frontend Agent (alternative to Figma) â For dev-only teams. Define design tokens in docs/specs/design-system/, choose a component library, and the /implement command generates UI from PRD requirements. No designer needed.
GitHub â Issue templates and CI workflow included.
The 4 maturity levels in this blueprint are a practical synthesis. They weren't invented in isolation â they combine industry frameworks, published research, and direct experience building products and technology with AI at the center.
- The integration of Obsidian + Claude Code + Figma Make as a unified workflow
- The specific mapping of Claude Code features (CLAUDE.md, skills, hooks, agent teams) to maturity levels
- The
[SPEC]convention and modular spec system - The blueprint structure itself â opinionated on where things go, flexible on what goes there
| Source | What it contributed | How it shaped the blueprint |
|---|---|---|
| Rushika Rai â AI Agent vs Agentic AI framework | 5 technical maturity levels (Level 0â4) measuring what the agent can do alone | Inspired the level-based structure, but we reframed it: our levels measure how the human changes their way of working, not just the agent's capability |
| OpenAI â Harness Engineering | The concept that engineers should design environments, constraints, and feedback loops â not write code. AGENTS.md as a map to deeper docs. Architectural guardrails as agent multipliers | Directly influenced L3 (hooks as automated gates) and the CLAUDE.md â docs/ structure. Our Obsidian vault is the equivalent of their structured docs/ directory |
| DX Research â Q4/2025 Impact Report | Data from 135k+ developers across 435 companies on AI adoption, time savings, and quality impact | Validated the progression: most teams are at L1 (copilot). Structured enablement is what moves teams forward, not just tool access |
| Steven Choi | Execution vs judgment distinction. Data showing Staff Engineers gain disproportionately more from AI agents. The "agentic context problem" warning | Reinforced why L3 and L4 exist: without governance and memory, L2 generates invisible tech debt at scale |
| Anthropic â Claude Code architecture | Skills, hooks, agent teams, CLAUDE.md convention, context compaction | The 4 levels map directly to Claude Code's feature progression: CLAUDE.md (L1) â skills + commands (L2) â hooks (L3) â agent teams + memory (L4) |
| Mitchell Hashimoto | The "harness" metaphor â every time an agent makes a mistake, engineer a solution so it never happens again | Shaped the L3 philosophy: hooks and gates aren't bureaucracy, they're compounding improvements |
| Ruben Hassid | Playbook for team adoption of Claude in 5 days using Projects and shared context | Informed how we think about L1âL2 transition for teams: adoption is an enablement problem, not a technology problem |
The key insight that ties it all together: most frameworks measure what AI can do. This one measures what humans need to change. An autonomous agent (L4) without the right human governance is just a faster way to generate tech debt. The levels exist to ensure that as AI capability increases, human oversight and context-keeping scale with it.
This is a living framework. As tools evolve and the community contributes, the levels will too. If you've found patterns that should be here, open an issue or PR.
This blueprint gives you the structure, but you need the fundamentals to use it well. All links below come directly from Anthropic's official documentation.
| What | Link | Why |
|---|---|---|
| Claude Code overview | code.claude.com/docs/en/overview | Understand what Claude Code is and choose your environment (CLI, VS Code, Desktop, Web) |
| Quickstart | code.claude.com/docs/en/quickstart | Walk through your first real task: explore a codebase, make changes, commit |
| Best practices | code.claude.com/docs/en/best-practices | Patterns that work, anti-patterns that don't. Read this before writing your first CLAUDE.md |
| What | Link | Why |
|---|---|---|
| CLAUDE.md and memory | code.claude.com/docs/en/memory | How to give Claude persistent instructions. The foundation of everything else |
| Common workflows | code.claude.com/docs/en/common-workflows | Plan mode, auto-accept, /compact, commit patterns |
| Settings | code.claude.com/docs/en/settings | Permissions, safety, environment variables |
| What | Link | Why |
|---|---|---|
| Skills | code.claude.com/docs/en/skills | Auto-invoked knowledge packs. How to create, trigger, and scope them |
| Extend Claude Code | code.claude.com/docs/en/features-overview | Map of all extension points: skills, subagents, hooks, MCP, plugins. Know when to use what |
| MCP servers | code.claude.com/docs/en/mcp | Connect Claude to external tools (Figma, GitHub, databases). Essential for the Figma Make flow |
| What | Link | Why |
|---|---|---|
| Hooks guide | code.claude.com/docs/en/hooks-guide | Automate gates: lint on write, security check on bash, audit on completion |
| Hooks reference | code.claude.com/docs/en/hooks | Full event schemas, JSON input/output, PreToolUse decision control |
| Plugins | code.claude.com/docs/en/plugins | Package skills + hooks + agents into shareable, installable units |
| What | Link | Why |
|---|---|---|
| Subagents | code.claude.com/docs/en/sub-agents | Create specialized agents with custom prompts, tools, permissions, and persistent memory |
| Agent teams | code.claude.com/docs/en/agent-teams | Multi-agent coordination: lead + teammates, shared tasks, peer-to-peer messaging. Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 |
| Claude Code SDK | code.claude.com/docs/en/sdk | Run Claude Code programmatically for CI/CD, automation, and custom orchestration |
| L4 Setup Guide | docs/l4-setup-guide.md | Step-by-step setup for Agent Teams, memory, and L4 hooks in this blueprint |
| What | Link | Why |
|---|---|---|
| How Claude Code works | code.claude.com/docs/en/how-it-works | Understand the agentic loop under the hood |
| Claude Code changelog | code.claude.com/docs/en/changelog | Stay current. Features evolve fast |
| Anthropic Academy | docs.claude.com/en/docs/anthropic-academy | Free interactive courses from Anthropic |
Note: Claude Code evolves fast. These links were verified against Claude Code v2.1.79 (March 2026). If a link breaks, check the Claude Code docs homepage for the updated path.
See CHANGELOG.md for the full evolution of the project â every feature, fix, and decision documented by date.
See CONTRIBUTING.md.
Created by @rtazima.
"Opinionated on structure, flexible on content."