Claude Best Practices Hub
abhayla/claude-best-practices
Padrões battle-tested e síntese automática de workflows para Claude Code
Ver no GitHubRepositório centralizado com padrões reutilizáveis (agents, skills, rules, hooks) para Claude Code. Oferece provisioning automático baseado na stack do projeto e síntese de padrões específicos do seu codebase via análise inteligente.
Instalação
npx convez-ai abhayla/claude-best-practices1 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
Casos de uso
- Provisionar patterns reutilizáveis em novos projetos
- Gerar regras, skills e agents específicos do seu codebase
- Implementar workflows orquestrados para testing, code-review e documentação
- Detectar e aplicar best practices conforme a tech stack
Veredito

Hub maduro e bem-estruturado para padronizar desenvolvimento com Claude Code. A síntese automática de padrões é poderosa, mas requer entendimento de como Claude analisa código — melhor para times que já usam Claude Code regularmente.
README
A tradução para o português deste README ainda está na fila.
Claude Best Practices Hub
A curated knowledge hub for Claude Code with two goals:
- Distribute reusable patterns — battle-tested agents, skills, rules, and hooks (for the live count, see
registry/patterns.json) that you provision into your projects. - Create, update, and maintain reusable workflows — orchestrated multi-step processes (testing, development, debugging, code-review, documentation, and more) that projects adopt to improve productivity.
Copy patterns to your project, or let /synthesize-project analyze your codebase and generate project-specific patterns automatically.
Getting Started
Prerequisites
- Claude Code CLI installed and working
- Git installed
- A project you want to add Claude Code patterns to
Step-by-step setup
Step 1: Clone this hub repo
git clone https://github.com/abhayla/claude-best-practices.git
cd claude-best-practices
Step 2: Install dependencies (only needed for smart provisioning or synthesis)
pip install -r scripts/requirements.txt
Step 3: Choose how to provision your project
You have three options. Pick the one that fits your needs:
Option A: Copy everything (simplest, no dependencies needed)
# Copy all patterns to your project
cp -r core/.claude/ /path/to/your/project/.claude/
Then delete what you don't need:
# Example: remove Android patterns if you don't use Android
cd /path/to/your/project
rm -f .claude/rules/android-*
rm -rf .claude/skills/android-*
rm -f .claude/agents/android-*
Option B: Smart provisioning (recommended for most users)
This auto-detects your project's tech stacks and copies only matching patterns:
# Run from the hub repo directory
cd claude-best-practices
PYTHONPATH=. python scripts/recommend.py --local /path/to/your/project --provision
This will:
- Detect your stacks (e.g., FastAPI + Android + Firebase)
- Copy matching hub patterns to your project's
.claude/ - Generate a
CLAUDE.mdandsettings.jsonfor your project - Show you what was copied
Option C: Full synthesis (most powerful — hub patterns + project-specific patterns)
This does everything Option B does, PLUS reads your actual source code and generates patterns unique to YOUR codebase.
# Step C1: First, provision your project with hub patterns (this also copies /synthesize-project skill)
cd claude-best-practices
PYTHONPATH=. python scripts/recommend.py --local /path/to/your/project --provision
# Step C2: Now open Claude Code in YOUR project
cd /path/to/your/project
claude
# Step C3: Inside Claude Code, run the synthesis skill
/synthesize-project --skip-hub
--skip-hub skips the hub provisioning step (you already did it in C1) and goes straight to analyzing your code.
What happens during synthesis:
- Claude Code reads your project's config files, entry points, and test files
- Identifies 10-20 conventions specific to your codebase
- Shows you what it found — you review and approve before anything is generated
- Generates rules (constraints), skills (workflows), and agents (review personas)
- Writes them to your
.claude/directory
For remote repos (you don't need the code locally):
# Run from the hub repo directory — creates a PR on the target repo
cd claude-best-practices
claude
/synthesize-project --repo owner/repo-name
After setup
Once your project has a .claude/ directory, you can use all the skills directly:
/development-loop Full build cycle: ideate → plan → implement → verify → commit
/implement Build a feature with TDD workflow
/fix-github-issue 42 Fix GitHub issue #42
/fix-loop Iterative fix until tests pass
/debugging-loop Structured bug diagnosis → fix → verify → learn
/tdd Strict red-green-refactor cycle
/continue Resume from previous session
/skill-master Find the right skill for any task
Keeping updated
# Inside Claude Code in your project — pulls latest from hub
/update-practices
What's Inside
| Component | Count | Description |
|---|---|---|
| Agents | 37 | Sub-agents for code review, debugging, testing, git, planning, security, docs — including 8 workflow-master orchestrators |
| Skills | 155 | Slash-command workflows: /implement, /fix-loop, /tdd, /synthesize-project, /development-loop, and more |
| Rules | 24 | Scoped coding rules for workflow, testing, FastAPI, Android, Compose, Firebase, etc. |
| Hooks | 8 | Auto-format, secret scanning, dangerous command blocking, context monitoring |
See core/.claude/README.md for the full catalog with descriptions.
Workflow Master Orchestration
Skills don't just run independently — they coordinate as teams. Each of the 8 workflow groups runs via a skill-at-T0 orchestrator (migration complete as of Phase 3, 2026-04-25). The skill body is injected into the user's T0 session and dispatches flat worker subagents via Agent() at T0 — the only reliably-parallel dispatch point in Claude Code per Anthropic's platform docs:
┌───────────────────────────┬──────────────────────────────┬──────────────────────────────────┐
│ Workflow │ Slash Command (T0) │ Worker subagents at T0 │
├───────────────────────────┼──────────────────────────────┼──────────────────────────────────┤
│ Testing Pipeline │ /test-pipeline │ test-scout, tester, │
│ scout → Wave 1+2 → │ (spec v2.2, Phase 3.1) │ fastapi-api-tester, │
│ JOIN → triage → │ │ visual-inspector, │
│ verify-affected → │ │ test-failure-analyzer, │
│ commit │ │ github-issue-manager, fixers │
├───────────────────────────┼──────────────────────────────┼──────────────────────────────────┤
│ Development Loop │ /development-loop │ plan-executor, │
│ ideate → plan → │ (Phase 3.2) │ planner-researcher │
│ execute → verify → │ │ │
│ commit │ │ │
├───────────────────────────┼──────────────────────────────┼──────────────────────────────────┤
│ Debugging Loop │ /debugging-loop │ debugger, │
│ diagnose → fix → │ (Phase 3.3) │ test-failure-analyzer │
│ verify → learn │ │ │
├───────────────────────────┼──────────────────────────────┼──────────────────────────────────┤
│ Code Review │ /code-review-workflow │ code-reviewer, │
│ gates → (deep audit) → │ (Phase 3.4) │ security-auditor │
│ PR → feedback │ │ │
├───────────────────────────┼──────────────────────────────┼──────────────────────────────────┤
│ Documentation │ /documentation-workflow │ docs-manager (optional, │
│ ADR → API docs → │ (Phase 3.5) │ bulk content drafting) │
│ structure → staleness │ │ │
├───────────────────────────┼──────────────────────────────┼──────────────────────────────────┤
│ Session Continuity │ /session-continuity │ session-summarizer │
│ save | restore | │ (Phase 3.6) │ (optional, deep summary) │
│ handover │ │ │
├───────────────────────────┼──────────────────────────────┼──────────────────────────────────┤
│ Learning │ /learning-self-improvement │ session-summarizer, │
│ capture → detect │ (Phase 3.7) │ context-reducer │
│ patterns → propose → │ │ (both optional) │
│ validate │ │ │
├───────────────────────────┼──────────────────────────────┼──────────────────────────────────┤
│ Skill Authoring │ /skill-authoring-workflow │ skill-author │
│ overlap-check → │ (Phase 3.8) │ (optional, richer drafts) │
│ author → validate → │ │ │
│ register │ │ │
└───────────────────────────┴──────────────────────────────┴──────────────────────────────────┘
Platform rationale: Anthropic's Claude Code does not forward the Agent
tool to dispatched subagents
(docs,
GH #19077,
GH #4182).
A dispatched subagent cannot dispatch further subagents — any Agent()
call in its body silently inlines at runtime. The skill-at-T0 pattern
relocates orchestration into the user's T0 session, where Agent() is
actually available; flat worker subagents can then be dispatched in
parallel via a single T0 assistant message.
T0 (user session)
│
├── project-manager-agent (full PRD-to-Production pipeline — T0-only)
│ │
│ └── invokes one of the 8 workflow skills below via Skill("/<workflow>")
│
├── /test-pipeline (skill-at-T0)
│ └── dispatches workers in ONE T0 message:
│ test-scout, tester, fastapi-api-tester, visual-inspector,
│ test-failure-analyzer, github-issue-manager, fixers
│
├── /development-loop (skill-at-T0) ├── /session-continuity (skill-at-T0)
├── /debugging-loop (skill-at-T0) ├── /learning-self-improvement (skill-at-T0)
├── /code-review-workflow (skill-at-T0) ├── /skill-authoring-workflow (skill-at-T0)
└── /documentation-workflow (skill-at-T0)
The 8 legacy <workflow>-master-agent files are deprecated: true
(Phase 3.1–3.8, 2-version-cycle window) and MUST NOT be dispatched.
Context passes between steps via structured return contracts — no skill starts
from scratch. For the canonical skill-at-T0 design, see
docs/specs/test-pipeline-three-lane-spec-v2.md
v2.2 (reference implementation) and
core/.claude/agents/workflow-master-template.md
v2.0.0 (canonical template).
docs/specs/workflow-master-agents-spec.md
is SUPERSEDED (Phase 3, 2026-04-25) and kept as historical record only.
How It Works
The two types of patterns
Hub patterns (generic, reusable) Project-specific patterns (yours)
core/.claude/rules/testing.md .claude/rules/api-result-wrapper.md
core/.claude/skills/tdd/SKILL.md .claude/skills/add-sqlalchemy-model/SKILL.md
core/.claude/agents/code-reviewer.md .claude/agents/meal-plan-reviewer.md
| |
| copied by recommend.py --provision | generated by /synthesize-project
+------ both end up in your .claude/ ------+
Hub patterns are generic best practices that work in any project of that stack. /implement, /fix-loop, /tdd — these are the same everywhere.
Project-specific patterns are conventions unique to YOUR codebase. "All endpoints must return through ApiResult[T]" or "Adding a Room entity requires updating 6 files" — only /synthesize-project can generate these because it reads your actual code.
/synthesize-project — provision + synthesize in one command
/synthesize-project Full flow: hub provision + code synthesis
/synthesize-project --repo owner/name Remote: analyze a GitHub repo, create a PR
/synthesize-project --skip-hub Synthesis only (no hub patterns)
/synthesize-project --skip-synthesis Hub patterns only (no code analysis)
/synthesize-project --update Re-scan after codebase changes
/synthesize-project --dry-run Preview without writing files
What it does:
- Provisions hub patterns — runs
recommend.py --provisionto copy matching stack patterns - Maps your project — reads config files, entry points, test files
- Identifies conventions — finds 10-20 candidate patterns (rules, skills, agents) and presents them for your review
- Gathers evidence — reads source files to confirm each convention, shows you what it found
- Generates patterns — creates
.claude/files with proper frontmatter, validated against hub standards - In remote mode — creates a PR on the target repo with all generated patterns
The skill presents detailed findings at two checkpoints so you see exactly what's being generated before any files are written.
/synthesize-hub — generalize patterns across projects (hub maintainer only)
When multiple projects independently synthesize similar patterns, the hub can learn from them:
/synthesize-hub Scan all bilateral-sync projects
/synthesize-hub owner/repo Scan a specific project
What it does:
- Collects
synthesized: truepatterns from downstream projects (with bilateral consent) - Clusters similar patterns using 3-level dedup (hash, structural, semantic)
- Classifies clusters: GENERALIZABLE (add to hub) vs STYLE (skip) vs DIVERGENT (skip)
- Drafts generalized patterns using the hub's creator tools (
/writing-skills,/claude-guardian) - Creates a PR for hub maintainer review
This is how the hub grows smarter over time — conventions that recur across 3+ projects get generalized into portable hub patterns.
Available Stacks
Stack-specific patterns use filename prefixes. recommend.py auto-detects your stacks:
| Stack | Prefix | What it adds |
|---|---|---|
fastapi-python | fastapi-* | API testing agent, DB admin agent, migration/deploy/test skills, backend rules |
android-compose | android-* | Compose agent, ADB testing, test runner skills, Android/Compose rules |
ai-gemini | ai-gemini-* | Gemini API reference skill |
firebase-auth | firebase-* | Firebase dev, AI, Data Connect, test skills |
react-nextjs | react-* | React Native dev, E2E testing skills |
flutter | flutter-* | Flutter dev, E2E testing skills |
vue-nuxt | vue-* / nuxt-* | Vue dev, Nuxt dev, Vue test skills |
bun-elysia | bun-elysia-* | Bun + Elysia dev rules, test skill |
Universal patterns (no prefix) are included for all stacks.
Key Skills
| Skill | What it does |
|---|---|
/synthesize-project | Provision hub patterns + generate project-specific patterns from your codebase |
/implement | Structured feature implementation with TDD workflow |
/fix-github-issue | Analyze and fix a GitHub issue end-to-end |
/fix-loop | Iterative fix cycle until tests pass |
/tdd | Strict red-green-refactor cycle |
/continue | Resume work from a previous session |
/writing-plans | Generate detailed implementation plans |
/brainstorm | Explore approaches before implementing |
/security-audit | Static analysis with CodeQL/Semgrep |
/update-practices | Pull latest patterns from hub |
/contribute-practice | Submit a local pattern to the hub |
/skill-master | Find the right skill for any task |
/development-loop | Full build cycle: ideate → plan → implement → verify → commit |
/test-pipeline | Three-lane test chain (skill-at-T0, spec v2.2): scout → Wave 1 (functional+api) → Wave 2 (UI) → JOIN → triage → verify → commit |
/e2e-visual-run | Playwright E2E with dual-signal verification + confidence-gated auto-heal (skill-at-T0) |
/debugging-loop | Structured diagnosis → fix → verify → learn |
/code-review-workflow | Quality gates → PR → review feedback |
See core/.claude/README.md for the full skills catalog.
Repository Structure
core/.claude/ # Distributable patterns (copy to your project)
agents/ # 37 specialized sub-agents (incl. 8 workflow masters)
skills/ # 155 slash-command workflows
rules/ # 24 scoped coding rules
hooks/ # 8 hook examples
settings.json # Minimal defaults
CLAUDE.md.template # Template for project CLAUDE.md
.claude/ # Hub-only operational config (NOT distributed)
skills/synthesize-hub/ # Collect + generalize patterns from projects
skills/scan-repo/ # Scan downstream repos
skills/scan-url/ # Scan internet sources
rules/rule-curation.md # Curation standards for hub patterns
config/ # Hub configuration
repos.yml # Registered downstream projects
settings.yml # Scan schedules, dedup thresholds, gold standards
config/workflow-contracts.yaml # Workflow DAGs with artifact contracts (8 workflows)
registry/patterns.json # Machine-readable index of all patterns (source of truth for the count)
scripts/ # Python tools (bootstrap, recommend, validate, sync, docs)
docs/ # Dashboard, getting started, sync architecture, flywheel
The Synthesize Flywheel
The hub isn't just a static library — it's a pattern compiler that gets smarter with every project:
Your project code
|
v
/synthesize-project ──> project-specific .claude/ patterns
| |
| (patterns that survive real usage)
| |
v v
/contribute-practice ──> hub PR (sanitized, generalized)
|
v
Hub grows smarter ──> better synthesis for the NEXT project
Sharing is opt-in and bilateral. By default, everything stays local. To participate in the flywheel, set allow_hub_sharing: true in .claude/synthesis-config.yml. See docs/synthesize-flywheel.md for the full design.
Contributing
Found a pattern that works well in your project?
- Run
/contribute-practice <pattern-path>inside Claude Code — validates, sanitizes project-specific content, and creates a PR - Or add it directly to
core/.claude/and open a PR. RunPYTHONPATH=. python scripts/workflow_quality_gate_validate_patterns.pyfirst.
All patterns must pass the curation standards: real source, real problem, not already covered.
License
MIT