convez.ai
SkillDesenvolvimento WebIntermediário
abhayla

Claude Best Practices Hub

abhayla/claude-best-practices

Padrões battle-tested e síntese automática de workflows para Claude Code

Ver no GitHub
InicialPluginScore · de 0 a 100

Repositó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-practices

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

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:

  1. Distribute reusable patterns — battle-tested agents, skills, rules, and hooks (for the live count, see registry/patterns.json) that you provision into your projects.
  2. 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.md and settings.json for 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:

  1. Claude Code reads your project's config files, entry points, and test files
  2. Identifies 10-20 conventions specific to your codebase
  3. Shows you what it found — you review and approve before anything is generated
  4. Generates rules (constraints), skills (workflows), and agents (review personas)
  5. 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

ComponentCountDescription
Agents37Sub-agents for code review, debugging, testing, git, planning, security, docs — including 8 workflow-master orchestrators
Skills155Slash-command workflows: /implement, /fix-loop, /tdd, /synthesize-project, /development-loop, and more
Rules24Scoped coding rules for workflow, testing, FastAPI, Android, Compose, Firebase, etc.
Hooks8Auto-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:

  1. Provisions hub patterns — runs recommend.py --provision to copy matching stack patterns
  2. Maps your project — reads config files, entry points, test files
  3. Identifies conventions — finds 10-20 candidate patterns (rules, skills, agents) and presents them for your review
  4. Gathers evidence — reads source files to confirm each convention, shows you what it found
  5. Generates patterns — creates .claude/ files with proper frontmatter, validated against hub standards
  6. 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:

  1. Collects synthesized: true patterns from downstream projects (with bilateral consent)
  2. Clusters similar patterns using 3-level dedup (hash, structural, semantic)
  3. Classifies clusters: GENERALIZABLE (add to hub) vs STYLE (skip) vs DIVERGENT (skip)
  4. Drafts generalized patterns using the hub's creator tools (/writing-skills, /claude-guardian)
  5. 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:

StackPrefixWhat it adds
fastapi-pythonfastapi-*API testing agent, DB admin agent, migration/deploy/test skills, backend rules
android-composeandroid-*Compose agent, ADB testing, test runner skills, Android/Compose rules
ai-geminiai-gemini-*Gemini API reference skill
firebase-authfirebase-*Firebase dev, AI, Data Connect, test skills
react-nextjsreact-*React Native dev, E2E testing skills
flutterflutter-*Flutter dev, E2E testing skills
vue-nuxtvue-* / nuxt-*Vue dev, Nuxt dev, Vue test skills
bun-elysiabun-elysia-*Bun + Elysia dev rules, test skill

Universal patterns (no prefix) are included for all stacks.


Key Skills

SkillWhat it does
/synthesize-projectProvision hub patterns + generate project-specific patterns from your codebase
/implementStructured feature implementation with TDD workflow
/fix-github-issueAnalyze and fix a GitHub issue end-to-end
/fix-loopIterative fix cycle until tests pass
/tddStrict red-green-refactor cycle
/continueResume work from a previous session
/writing-plansGenerate detailed implementation plans
/brainstormExplore approaches before implementing
/security-auditStatic analysis with CodeQL/Semgrep
/update-practicesPull latest patterns from hub
/contribute-practiceSubmit a local pattern to the hub
/skill-masterFind the right skill for any task
/development-loopFull build cycle: ideate → plan → implement → verify → commit
/test-pipelineThree-lane test chain (skill-at-T0, spec v2.2): scout → Wave 1 (functional+api) → Wave 2 (UI) → JOIN → triage → verify → commit
/e2e-visual-runPlaywright E2E with dual-signal verification + confidence-gated auto-heal (skill-at-T0)
/debugging-loopStructured diagnosis → fix → verify → learn
/code-review-workflowQuality 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?

  1. Run /contribute-practice <pattern-path> inside Claude Code — validates, sanitizes project-specific content, and creates a PR
  2. Or add it directly to core/.claude/ and open a PR. Run PYTHONPATH=. python scripts/workflow_quality_gate_validate_patterns.py first.

All patterns must pass the curation standards: real source, real problem, not already covered.


License

MIT

Ver o original no GitHub

Bom para

Relacionados