Dev Best Practices
gerfru/dev-best-practices
24 skills de best practices para design, review e debug de projetos
Ver no GitHubColeção de 24 skills opinionadas para Claude Code que cobrem design, review, debug e testes de projetos de software. Inclui práticas em arquitetura, segurança, LLM, observabilidade e CI/CD, fundamentadas em currículos de MIT, CMU e Stanford.
Instalação
npx convez-ai gerfru/dev-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
- Auditar arquitetura e acoplamento de sistemas
- Revisar segurança (crypto, injeção, GDPR, EU AI Act)
- Design de APIs REST/GraphQL e schemas de dados
- Estratégias de zero-downtime migrations
- Avaliação e otimização de sistemas LLM
- Debug com análise de root-cause e sugestões de fix
Veredito

Excelente referência prática para engenheiros que buscam elevar o padrão técnico. A cobertura é ampla (design, segurança, LLM, observabilidade), mas requer interpretação — não é automação pura, e sim guia estruturado que Claude ajuda a aplicar. Ideal para times que querem decisões informadas por pesquisa acadêmica.
README
A tradução para o português deste README ainda está na fila.
Dev Best Practices
Opinionated best-practice rules for software projects — RAG systems, AI agents, data pipelines, full-stack web apps. Three detail levels: compact essential rules for CLAUDE.md, thematic rule files, and detailed reference docs.
Also a Claude Code plugin: install once, get 24 skills in every project.
Quick Start
# Add marketplace (once per machine)
claude plugin marketplace add gerfru/dev-best-practices
# Install plugin
claude plugin install dev@gerald-dev-best-practices
# Open navigation menu
/dev:meta-help
Windows (VS Code): Claude icon → /plugin → Marketplaces → add gerfru/dev-best-practices → Plugins → Install dev.
Skills
Start with /dev:meta-help — shows the full menu and launches any skill directly.
Or just describe what you need in natural language — Claude picks the right skill automatically.
Design
| Skill | What it does |
|---|---|
/dev:design-app | Stack & architecture decisions from the rule files |
/dev:design-secure | Threat model, crypto selection, auth, compliance |
/dev:design-api | REST / GraphQL / gRPC contract design or review |
/dev:design-data | Schema, normalization, indexes, CQRS / Event Sourcing |
/dev:design-migration | Zero-downtime strategy: Expand-Contract, Strangler Fig, Saga |
/dev:design-ux | UX/UI design: interaction model, trust, AI features, anti-patterns |
/dev:design-llm | LLM system: RAG, fine-tune vs. prompt, agents, evals, guardrails |
/dev:design-observability | SLO/SLI, Golden Signals, tracing, alerting, incident response |
/dev:design-cicd | CI/CD pipeline, deployment strategies (Blue-Green, Canary), DORA |
/dev:design-iac | Infrastructure as Code: Terraform, GitOps, state management, drift detection |
Review
| Skill | What it does |
|---|---|
/dev:review-app | Full audit across 6 axes (architecture, security, tests, CI/CD, …) |
/dev:review-arch | Coupling, anti-patterns, quality attributes, ADR recommendations |
/dev:review-secure | Crypto, injection, memory safety, GDPR / ISO 27001 / EU AI Act |
/dev:review-ux | UX audit based on HAX, PAIR, CHI 2024 and Nielsen Norman |
/dev:review-llm | LLM audit: architecture, evals, prompt injection, OWASP LLM Top 10 |
Tools
| Skill | What it does |
|---|---|
/dev:tool-debug [error] | Root-cause analysis with stack-aware fix suggestions |
/dev:tool-test [focus] | Write missing tests or design test strategy per test pyramid |
/dev:tool-style [task] | CSS solution matching your existing system (Tailwind, SCSS, …) |
/dev:tool-a11y | Accessibility audit: WCAG 2.2, screen reader testing, EU Accessibility Act |
/dev:tool-perf [symptom] | Performance engineering: USE Method, flame graph, bottleneck analysis, Bentley Rules |
Meta
| Skill | What it does |
|---|---|
/dev:meta-help | Navigation menu — shows all 24 skills, launches chosen one |
/dev:meta-install | Insert essential-rules.md into project CLAUDE.md (detects install vs. update) |
/dev:meta-drift | Compare installed rules block against current rule files |
/dev:meta-sync | Repo-internal: check if claude/*.md still reflects reference/*.md |
/dev:meta-create-skill | Build a new skill: clarify topic, research academic basis, write all files |
Repo Structure
.claude-plugin/
marketplace.json Makes this repo installable as a marketplace
plugins/dev/
.claude-plugin/
plugin.json Plugin metadata (name: "dev", version: "2.0.0")
commands/ Slash-command definitions (one file per skill)
skills/ Skill workflow definitions (auto-triggered)
rules/ Mirror of claude/*.md (used by skills as reference)
claude/ Condensed rules for Claude Code
essential-rules.md ~80 lines — copy into project CLAUDE.md
app-rules.md App rules in detail
github-rules.md GitHub / CI rules in detail
architecture-rules.md Architecture rules in detail
reference/ Detailed docs for humans
app-best-practices.md Security, auth, API, DB, monitoring, OWASP
github-best-practices.md CI/CD, linting, testing, Docker, code review
architecture-best-practices.md Layers, patterns, infra, 12-Factor
docs/
skill-research-basis.md Academic & industry sources per skill
scripts/
validate-skills.sh Plugin structure validator (CI + pre-commit)
Using Rules Without the Plugin
Option 1 — Essential rules only (recommended for most projects)
Copy claude/essential-rules.md into your project's CLAUDE.md — or use /dev:meta-install to do it automatically with version markers.
Option 2 — Add more depth
Pick sections from claude/app-rules.md, claude/github-rules.md, or claude/architecture-rules.md and append selectively.
Option 3 — Global rules
Put rules that apply to every project in ~/.claude/CLAUDE.md:
- Linting / formatting standards
- Git workflow
- Security baseline
Typical Workflows
New project:
/dev:meta-install → inserts essential-rules.md into CLAUDE.md
/dev:design-app → architecture & stack decisions
/dev:design-secure → threat model & security design
Before release:
/dev:review-app → full audit
/dev:review-secure → security code review
/dev:tool-a11y → accessibility check (EU Accessibility Act)
During development:
/dev:tool-debug [error] → root-cause analysis
/dev:tool-test → write missing tests
/dev:tool-style [task] → CSS fix in your system's style
LLM / AI features:
/dev:design-llm → RAG vs. fine-tune decision, agent architecture
/dev:review-llm → audit existing LLM system (OWASP LLM Top 10)
Keep rules up to date:
/dev:meta-drift → what changed since last install?
/dev:meta-install → update in-place (preserves project exceptions)
Maintenance
# Sync rule mirrors after editing claude/*.md
cp claude/*.md plugins/dev/rules/
# Validate plugin structure locally
bash scripts/validate-skills.sh
# Run all checks (markdownlint + link check + skill validation)
pre-commit run --all-files
CI runs on every PR: markdown lint → skill validation → link check → secret scan.
Troubleshooting
Skills don't appear after install: run /reload-plugins.
Unrecognized token when adding marketplace: a JSON file has a BOM. Fix:
Get-ChildItem -Recurse -File -Path .claude-plugin,plugins | ForEach-Object {
$c = Get-Content -Raw -LiteralPath $_.FullName
[System.IO.File]::WriteAllText($_.FullName, $c, (New-Object System.Text.UTF8Encoding($false)))
}
Then push and re-add the marketplace on the client.
claude plugin marketplace ... unknown command (older Claude Code): use slash commands instead — /plugin marketplace add ....