convez.ai
SkillDevOps & InfraestruturaIntermediário
asspenwhite

Claude Code Framework

asspenwhite/claude-code-framework

Template de produção para Claude Code com hooks, playbooks e loops de verificação

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework completo e minimalista para operacionalizar Claude Code em projetos reais. Fornece estrutura de documentação, regras de IA, hooks de segurança e playbooks prontos para usar Claude como operador de sistemas (redes, infraestrutura, SaaS), não apenas assistente de codificação.

Instalação

$npx convez-ai asspenwhite/claude-code-framework

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
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Administração de redes e infraestrutura com Claude Code
  • Operação de sistemas SaaS e hypervisores (Proxmox, Docker)
  • Manutenção de bases de conhecimento integradas com Obsidian
  • Configuração de verificação adversarial e auditoria antes do deploy

Veredito

Framework sólido e battle-tested para escalar Claude Code além de codificação simples. Excelente para quem opera sistemas reais e precisa de garantias (hooks, auditoria, verificação). Recomendado para DevOps e infraestrutura; requer disciplina de processo para valer.

README

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

Claude Code Framework

A lightweight project template for Claude Code — documentation structure, AI rules, working hooks, and battle-tested playbooks for running Claude Code as an operator, not just a coding assistant.

Use this template


Apply to a Project

Open Claude Code in any project and say:

Apply the claude-code-framework from https://github.com/asspenwhite/claude-code-framework to this project.

Claude will clone the framework, copy CLAUDE.md + docs/ + .claude/ into your project, and customize for your stack (it will ask for project name, description, and tech stack).

Manual setup

cd /path/to/your/project
git clone --depth 1 https://github.com/asspenwhite/claude-code-framework.git temp
cp temp/CLAUDE.md ./
cp -r temp/docs temp/.claude ./
rm -rf temp
claude

Operating a system (network, hypervisor, live service)

Read docs/playbooks/README.md, pick the playbook nearest your role, and ask Claude to bootstrap the workspace from it — starting read-only: snapshot state, write the AS-BUILT, then plan.


What You Get

  • Progressive disclosure -- Claude reads what it needs when it needs it
  • Working hooks, active on clone -- secrets-path protection now, audit-log Stop gate opt-in. CLAUDE.md for guidance, hooks for guarantees
  • A verification loop -- a named Check command + an adversarial-reviewer subagent that attacks the diff in fresh context before work is called done
  • A self-improvement loop -- /retro harvests session corrections into hooks, CLAUDE.md lines, and docs, so the setup compounds
  • MCP integration -- points Claude to Obsidian, context7, Playwright
  • Plugin-first -- uses official Claude Code plugins instead of custom skills
  • Doc templates -- CHANGELOG, TODO, DECISIONS, API, SCHEMA — plus ops templates: INCIDENT, AS-BUILT, RUNBOOK
  • Role playbooks -- network admin, virtualization admin, SaaS operator, knowledge base — distilled from daily production use

This is intentionally minimal. The real power comes from Claude Code's plugin ecosystem, MCP servers, and hooks — not static markdown files.


Beyond Coding: The Playbooks

Claude Code runs real systems well when you give it an operating contract. These playbooks are how this framework is actually used day-to-day — genericized for public consumption:

PlaybookRole
docs/playbooks/NETWORK_ADMIN.mdNetwork administrator (UniFi-style controller APIs, VLAN work, firewall policy)
docs/playbooks/VIRTUALIZATION_ADMIN.mdProxmox / hypervisor / homelab admin (VMs, GPU passthrough, Docker stacks)
docs/playbooks/SAAS_OPERATOR.mdWebsite / SaaS operator (sprint loop with adversarial review, ADRs, launch gates)
docs/playbooks/KNOWLEDGE_BASE.mdKnowledge-base maintainer (Obsidian vault as Claude's cross-project memory)

Shared doctrine: a repo per system · AS-BUILT vs DRAFT-plan separation · append-only audit CHANGELOG · read-only by default · same-day incident reports. Details in docs/playbooks/README.md.


Hooks: Guarantees, Not Guidance

CLAUDE.md instructions are advisory — followed most of the time. Hooks are deterministic — every time. Anything that must happen without exception (lint after edit, protected paths, audit-log entries, verification gates) belongs in a hook. docs/HOOKS.md covers the events that matter, exit-code semantics, five starter recipes, and lessons from running hooks in production (including why over-hooking backfires).


Recommended Plugins

Install from the official marketplace. These load on-demand -- no startup cost.

/plugin install code-review@claude-plugins-official
/plugin install security-guidance@claude-plugins-official
/plugin install frontend-design@claude-plugins-official
/plugin install pr-review-toolkit@claude-plugins-official
/plugin install commit-commands@claude-plugins-official

Or browse interactively with /plugin. All five names verified against the official marketplace (June 2026).


Recommended MCP Servers

These give Claude capabilities its built-in tools can't match.

# Up-to-date library docs (React, Next.js, Prisma, etc.)
claude mcp add context7 -- npx -y @upstash/context7-mcp

# Browser control for visual testing
claude mcp add playwright -- npx @playwright/mcp@latest

# Obsidian vault for cross-project knowledge (if you use Obsidian)
# See: https://github.com/MarkusPfundstein/mcp-obsidian

Setup details: docs/MCP.md


What's Included

CLAUDE.md                          -- AI instructions template (customize this)
.claude/
  settings.json                    -- hook wiring (protect-paths active on clone)
  hooks/
    protect-paths.sh               -- PreToolUse: blocks Edit/Write to secrets paths (ACTIVE)
    docs-sync-gate.sh              -- Stop: no turn ends with unlogged changes (opt-in)
  agents/
    adversarial-reviewer.md        -- fresh-context diff attacker (subagent)
  skills/
    retro/SKILL.md                 -- /retro: harvest session corrections into durable config
docs/
  ARCHITECTURE.md                  -- How progressive disclosure works
  WORKFLOW.md                      -- Documentation workflow guide
  HOOKS.md                         -- Deterministic guarantees: events, recipes, lessons
  MODEL_NOTES.md                   -- Claude 5 / Opus 4.8 era notes, proactiveness controls, migration
  MCP.md                           -- MCP server setup guide
  FILE_FORMATS.md                  -- Token-efficient format guidelines
  CLAUDE.md.example                -- Full CLAUDE.md example
  playbooks/                       -- Role playbooks (network, virtualization, SaaS, knowledge base)
  templates/                       -- Doc templates (CHANGELOG, TODO, DECISIONS, INCIDENT, AS-BUILT, RUNBOOK, ...)

/retro — The Compounding Loop

The one custom skill. Run it at the end of a session: it harvests corrections, repeated friction, and hard-won discoveries, routes each to its durable home (a hook if it must hold 100% of the time, a CLAUDE.md line if it needs judgment, docs if it's project fact), and prunes CLAUDE.md so it never bloats. Your setup gets better every session instead of staying static.


Philosophy

  1. Plugins over skills. Official plugins are maintained upstream, load on-demand, and don't bloat your context window. Don't reinvent them as markdown files.
  2. MCP over static knowledge. A running Obsidian vault or context7 server has live data. A SKILL.md has stale data.
  3. Hooks over repetition. If a CLAUDE.md rule keeps getting violated, don't write it louder — make it a hook and delete the prose.
  4. Less is more. Every line in CLAUDE.md costs context tokens. Keep it short, point to docs/ for detail.
  5. If it changed, log it. If it broke, write the incident. The audit CHANGELOG and incident corpus become institutional memory Claude reads on demand.
  6. Templates over prescriptions. This framework gives you structure. You fill in the content.

Model-Era Notes

v1.9 is tuned for the Claude 5 era (Fable 5 / Opus 4.8). What carried over from earlier model generations, what was retired (including the old adaptive-thinking client patch — do not apply it anymore), proactiveness controls, and a migration checklist: docs/MODEL_NOTES.md.


License

MIT

Ver o original no GitHub

Bom para

Relacionados