convez.ai
MCP ServerAutomaçãoIniciante
faizkhairi

Claude Code Blueprint

faizkhairi/claude-code-blueprint

Biblioteca modular para evitar erros comuns do Claude Code

Ver no GitHub
BomPluginScore · de 0 a 100

Arquitetura de referência testada em produção para Claude Code, agnóstica de framework. Fornece 11 agents, 17 skills, 10 hooks e 5 regras prontas para copiar e adaptar ao seu projeto, com suporte a adoção graduada (mínima até completa).

Instalação

$npx convez-ai faizkhairi/claude-code-blueprint

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
73
Forks
24
Acompanhando
1
Saúde
100%
Último commit
há 3 dias
Versão
v1.3.2
Issues abertas
8
Contribuidores
2

Casos de uso

  • Estruturar projetos de código com Claude de forma confiável
  • Implementar regras de verificação pós-execução e diagnóstico prioritário
  • Adicionar camadas de validação e automação sem overhead de contexto

Veredito

Blueprint bem pensado e modular que reduz erros de IA em fluxos de código. Modelo de adoção graduada é inteligente, mas demanda disciplina do usuário para não virar técnico-debt de contexto.

README

A tradução para o português deste README ainda está na fila.

Claude Code Blueprint

Prevent the most common AI coding mistakes — a library of ready-to-copy files (CLAUDE.md, hooks, agents) you mix into your own project to make Claude Code more reliable.

60 seconds to start. Copy one file. Add more as your project grows. Works with any language, any framework, any skill level.

Stars Forks License Claude Code PRs Welcome

11 agents · 17 skills · 10 hooks · 5 rules — copy only what you need, or install a preset (minimal / standard / core / full)

English | 日本語 | 한국어 | 简体中文


Heads up before you copy: This is a reference repo, not a project template — you'll copy files OUT of it into your own project. Don't run Claude Code inside this repository (it'll load this blueprint's CLAUDE.md instead of yours). See GETTING-STARTED.md for the full walkthrough.


Quick Start

Copy one file. Get three behavioral rules. Done in 60 seconds.

# In your project root
curl -o CLAUDE.md https://raw.githubusercontent.com/faizkhairi/claude-code-blueprint/main/CLAUDE.md

This gives Claude Code three rules that prevent the most common AI coding mistakes:

Verify-After-Complete · Diagnose-First · Plan-First

Ready for more? See the full adoption path or the 30-minute beginner guide. New to Claude Code? See who this is for or the FAQ.

Want more than CLAUDE.md? Install hooks, agents, and settings automatically:

# From a cloned/forked copy of this repo
./setup.sh --preset=standard

Or let Claude do it -- paste into a Claude Code session: "Set up the Claude Code Blueprint. Copy CLAUDE.md to my project root, set up hooks and settings in ~/.claude/. Show me each step."

See SETUP.md for all setup options including a verification checklist.


What It Costs You (Token Budget)

Every file you copy is a recurring per-session context cost. Here is what each component costs and when it loads, so you can decide what to add. Numbers are measured from the actual files (~4 characters per token):

ComponentToken CostWhen It Loads
CLAUDE.md~2,300Every session start
An always-on rule (session-lifecycle)~700Every session
A path-scoped rule (testing, schema, api)~850-1,450Only when editing matching files — otherwise zero
A skill (review-full, test-check, deploy-check)~480-1,070Only when its trigger phrase is used
Hooks (all of them)ZeroThey run outside Claude's context
An agent (per spawn)Full context windowOnly when you invoke it

The economics: hooks cost zero tokens, and path-scoped rules cost nothing until you touch a matching file. The recurring baseline is just CLAUDE.md (~2,300 tokens, roughly 3-5% of a typical session) — and a single prevented redo cycle saves far more than that. See the full breakdown and savings math.


Who Is This For?

Any developer, any framework, any skill level. The blueprint configures Claude Code's behavior -- it doesn't care what language or framework your project uses.

You AreStart HereTime to Value
Complete beginnerStart Here1 minute: just copy CLAUDE.md
Solo dev, small projectCLAUDE.md + 2 hooks5 minutes
Small startup (2-5 devs)Above + shared rules + 2-3 agentsSee Team Setup
Established team (5+ devs)Full blueprint, adaptedFork, customize, commit shared config
Learning to codeGETTING-STARTED.md onlyIgnore agents/skills/memory until comfortable
Coming from another toolCROSS-TOOL-GUIDE.mdConcepts transfer; see Copilot/Cursor in depth sections

Your Progression

Level 1 -- Start here (60 seconds) Copy CLAUDE.md into your project. Three behavioral rules. Immediate impact.

Level 2 -- Add safety nets (5 minutes) Add 2-3 hooks. Zero token cost. Automated config protection and edit verification.

Level 3 -- Customize as you grow (ongoing) Add agents, skills, rules, and memory as your workflow matures. The core preset is a good next step -- a curated set of review/test/deploy skills and two path-scoped rules, without the full specialist ecosystem. See Presets for ready-to-copy configurations.


What Makes This Different

Other repos dump dozens of agents on you. We give you 11 -- and explain why each one exists.

This BlueprintGeneric Config Repos
Every component has a battle story explaining why it existsConfigs without context
3 behavioral rules that prevent AI coding mistakesLists of settings to copy
Cross-tool guide for 10 other tools (Copilot, Cursor, Cline, Roo Code, OpenCode, and more)Single-tool only
Beginner-friendly with 6 adoption personasAssumed expertise
Smoke-tested hooks with 35 automated testsUntested scripts
Safety-first: config placement guide, privacy warnings, graceful degradationNo safety guidance
Framework-agnostic: works with any language and stackAssumes a specific language/framework

What's Inside

 

AgentModelRole
project-architectopusSystem design, architecture decisions, technology choices
backend-specialistsonnetAPI endpoints, services, database operations, middleware
frontend-specialistsonnetUI components, state management, forms, styling
code-reviewersonnetCode quality, patterns, best practices (read-only)
security-reviewersonnetOWASP Top 10, auth flaws, injection attacks (read-only)
db-analystsonnetSchema analysis, query optimization, migration planning (read-only)
devops-engineersonnetDeployment configs, CI/CD, Docker, infrastructure (read-only)
qa-testersonnetUnit tests, integration tests, E2E tests
verify-plansonnet7-point mechanical plan verification (read-only)
docs-writerhaikuREADME, API docs, changelogs, architecture docs
api-documenterhaikuOpenAPI specs, integration guides (read-only)

See agents/README.md for permission modes, cost estimates, and maxTurns.

 

CategorySkillsTriggers
Code Qualityreview-full, review-diff"is this secure?", "scan diff", "check for vulnerabilities"
Testingtest-check, e2e-check"run the tests", "browser test", "are tests passing?"
Deploymentdeploy-check"deploy", "push to prod", "ready to ship"
Planningsprint-plan, elicit-requirements"let's build", "new feature", multi-step tasks
Sessionload-session, save-session, session-end, save-diarySession start/end, "save", "bye", "done"
Projectscaffold-project, register-project, status, changelog"new project", "status", "changelog"
Databasedb-check"check the schema", "validate models"
Utilitiestech-radar"what's new?", "should we upgrade?"

See skills/README.md for customization and placeholder variable setup.

 

EventHookPurpose
SessionStartsession-start.shInject workspace context
PreToolUse (Bash)block-git-push.shProtect remote repos
PreToolUse (Write/Edit)protect-config.shGuard linter/build configs
PostToolUse (Write/Edit)notify-file-changed.shVerify reminder
PostToolUse (Bash)post-commit-review.shPost-commit review
PreCompactprecompact-state.shSerialize state to disk
Stopsecurity check + cost-tracker.sh + session-checkpoint.shLast defense + metrics
SessionEndsession-checkpoint.shGuaranteed final save

Plus 2 utility scripts: verify-mcp-sync.sh (MCP config checker) and status-line.sh (branch/project status). The 11th file in the folder is test-hooks.sh — the local test harness, run via bash hooks/test-hooks.sh to verify all hooks. It's not deployed to ~/.claude/hooks/ and isn't counted in the "10 hooks" total.

Run bash hooks/test-hooks.sh to verify all hooks pass (35 automated tests).

See hooks/README.md for the full lifecycle, testing guide, and design principles.

 

RuleActivates OnPurpose
api-endpoints**/server/api/**/*.{js,ts}API route conventions
database-schema**/prisma/**, **/drizzle/**, **/migrations/**Schema design patterns
testing**/*.test.*, **/*.spec.*Test writing conventions
session-lifecycleAlwaysSession start/end behaviors
memory-session**/memory/**Memory repository session management

See rules/README.md for creating custom rules.

Also included:

ComponentPurpose
CLAUDE.mdBattle-tested behavioral rules template
Settings TemplateFull hook + permission configuration
Memory SystemBuilt-in opt-in: Claude remembers preferences and session context across runs (git-ignored for privacy)

Philosophy

  1. Hooks for enforcement, CLAUDE.md for guidance -- Hooks fire deterministically every time. CLAUDE.md instructions are followed most of the time, but not guaranteed -- the model can forget or deprioritize a rule. If something MUST happen, make it a hook.

  2. Agent-scoped knowledge, not global bloat -- Design principles live in the frontend agent, not in every session's context. Security patterns live in the security-reviewer, not in CLAUDE.md.

  3. Context is currency -- Every token loaded into context is a token not available for your code. Keep MEMORY.md under 100 lines. Extract to topic files. Use path-scoped rules so irrelevant rules don't load.

  4. Hooks are free, context is cheap -- The 10 hook scripts cost zero tokens (they run outside Claude's context). CLAUDE.md adds ~2,300 tokens per session -- roughly 1-5% of a typical session. The blueprint saves more tokens than it costs by preventing redo cycles. See BENCHMARKS.md.

  5. Battle-tested over theoretical -- Every rule in this repo exists because something went wrong without it. The "WHY" matters more than the "WHAT".


Getting Started

Option A: Fork (recommended)

Fork this repo to customize it as your own living reference. You can pull upstream updates later as the blueprint evolves.

Option B: Clone + Copy

Clone the repo, then selectively copy components into your ~/.claude/ directory.

Option C: Cherry-pick

Browse the repo on GitHub and copy only the specific files you need. No installation required.

Option D: Automated Setup

Run ./setup.sh from a cloned or forked copy. Choose a preset (minimal/standard/core/full) and the script handles directory creation, file copying, settings merge, and placeholder replacement. See SETUP.md.

Recommended adoption path

  1. Start with CLAUDE.md -- the behavioral rules template. Biggest impact with zero setup.
  2. Add 2-3 hooks -- protect-config.sh + notify-file-changed.sh + cost-tracker.sh. Copy to ~/.claude/hooks/ and wire into settings.json.
  3. Read WHY.md to understand the reasoning -- adapt, don't blindly copy.
  4. Add agents as your workflow matures -- start with verify-plan and code-reviewer.
  5. Set up the memory system when you need cross-session persistence — opt-in during ./setup.sh (answer Y).

Deep Dives

ArchitectureSettings GuideBattle Stories
System design, hook lifecycle, component relationshipsEvery env var, permission, and hook explained with rationaleThe incidents and lessons behind every component
BenchmarksPresetsCross-Tool Guide
Token savings, cost impact, quality metricsReady-to-copy configs for solo, team, and CI/CDCopilot, Cursor, Cline, Roo Code, OpenCode, and more (10 other tools)
FAQGetting StartedTroubleshooting
Top community questions answeredFrom zero to productive in 30 minutesCommon issues and fixes
Setup GuideCase StudiesRoadmap
Automated installer + verification checklistAdopter stories and before/after metrics (submission-driven — be the first)Project direction and what's next
Self-Monitoring
Optional patterns: gitleaks pre-commit + memory-curator agent

Common Questions

Works with my framework? Yes. The blueprint is framework-agnostic -- it configures Claude Code, not your stack. More...

Too advanced for me? No. Start with one file (CLAUDE.md). Add more only when you need it. More...

Which plan do I need? Works on Pro, Max, Team, Enterprise, and API. Hooks are free on all plans. More...

A colleague sent you this? Start here: quickstart for referrals.


 

This blueprint is designed as a standalone configuration -- no plugins required. In fact, plugins can interfere with a custom setup:

Known issues:

  • Plugins that modify CLAUDE.md may overwrite your custom behavioral rules
  • Plugins that add hooks on the same events (e.g., Stop, PreToolUse) will stack with your hooks -- this can cause slowdowns or conflicting instructions
  • Plugins that inject context consume tokens from your context window, leaving less room for your agents and memory system
  • MCP server plugins work well alongside this setup -- they add tools, not rules, so there's no conflict

Recommendation: If you adopt this blueprint, audit your installed plugins and disable any that:

  1. Override CLAUDE.md or settings.json hooks
  2. Inject prompts on SessionStart (conflicts with your session-lifecycle rule)
  3. Add broad permissions that bypass your permission restrictions

Custom setup > generic plugins, because your setup encodes YOUR project's domain knowledge. A plugin can't know your architecture, your team's conventions, or your production constraints.


Acknowledgments

The memory system pattern in this blueprint was inspired by Project-AI-MemoryCore by Kiyoraka — a comprehensive AI memory architecture with 11 feature extensions (LRU project management, memory consolidation, echo recall, and more). If you want a deeper, more feature-rich memory system than the lean built-in version here, check out that project.

How they differ: This blueprint covers the full Claude Code configuration (agents, skills, hooks, rules, settings) and ships a built-in opt-in memory in memory/. Project-AI-MemoryCore goes deep on the memory layer specifically — they're complementary, not competing.

License

MIT

Ver o original no GitHub

Bom para

Relacionados