Claude Engineering Skills para Java/Spring
fmodesto30/claude-engineering-skills
Lentes de review e construção de specs para engenharia Java/Spring produtiva
Ver no GitHubConjunto de skills reutilizáveis para code review e arquitetura em Java/Spring Boot, incluindo lentes de avaliação (PR review, architecture review), checklists de design patterns, DDD, SOLID e produção. Implementa severity-calibration (MUST/SHOULD/NIT) para feedback técnico objetivo, focando em correção, transações, idempotência e risco produtivo — não em estilo.
Instalação
npx convez-ai fmodesto30/claude-engineering-skills1 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
- Code review automatizado de pull requests com critérios consistentes
- Revisão arquitetural de designs antes da implementação
- Authoring de especificações spec-driven para novas features
- Autoeducação de juniors em patterns, DDD, SOLID e produção
Veredito

Ferramenta madura e opinada para times Java que buscam elevar qualidade de code review sem retipar feedback repetitivo. A arquitetura de lentes + skills + severity-rubric é bem pensada; demanda curva de aprendizado e customização por stack específico, mas o retorno em consistência é real.
README
A tradução para o português deste README ainda está na fila.
claude-engineering-skills
Original, sanitized software-engineering review skills for Claude Code. First focus: Java / Spring Boot — reviewing changes (pull-request and architecture review) and authoring the specs that drive them (spec-driven construction). Both tracks share the same lenses.
These are reusable review lenses — checklists, heuristics, and severity rubrics that let Claude apply the same engineering judgment to every PR, so reviewers stop retyping the same comments and juniors can self-review before asking.
Learn from this repository
Drop this repo into any Claude CLI, open a session in it, and say "APRENDA COM ESSE REPOSITÓRIO" (or "learn from this repository"). The agent loads CLAUDE.md, reads every skill and lens in full, summarizes what it learned, and then proposes how to adopt the skills durably in your environment (install them so they auto-trigger every session, or adapt them to your stack) — staying read-only until you approve. See the Learn protocol.
Philosophy
- A pattern or rule is a tool, never a goal. Nothing is flagged unless a concrete consequence can be named.
- Severity-calibrated. Every finding is
MUST/SHOULD/NIT/NO_COMMENT. Preferences never block a PR. See severity-rubric.md. - Style belongs to tooling, not review.
final var,this., import order, formatting, and "useless comment" removal are a linter's job (Checkstyle, Spotless, PMD, Sonar) — not an AI review finding. The skills spend their attention on reasoning-heavy concerns: correctness, transactions, idempotency, design, and production risk. - Modern-first. Prefer current Java/Spring idioms (records, sealed types, pattern matching,
functional interfaces, DI,
ApplicationEventPublisher) over classic pattern ceremony — and always inspect the target project's actual stack before recommending anything. - Few strong comments over many weak ones. One well-justified
MUSTbeats a wall of nits.
Architecture model
- Skill = a mode of work / workflow (
skills/<name>/SKILL.md). - Lens = reusable specialized knowledge (
lenses/<topic>.md), loaded by skills on demand. - Template = output format (
templates/…). - Rule = a global rule (
rules/), e.g. the severity rubric shared by every skill. - Hook = deterministic enforcement — the sanitization gate (
scripts/sanitization-check.sh, run in CI and as a pre-commit hook).
Knowledge lives in lenses and is shared across skills; each skill declares which lenses it uses
and how it uses them — the same lens serves a different intent across two tracks: review
skills (java-pr-review, architecture-review) read it evaluatively, to judge code or a design
that already exists, while construction skills (spec-author) read the same lens
generatively, to decide what to build. Skills are created per type of work, never per book
or per pattern.
Structure
lenses/
├── agent-skills.md # (meta) Claude Code skill & .claude/ config best practices
├── cdc.md # capturing & streaming committed datastore changes
├── clean-code.md # readability & maintainability of changed code
├── cqrs.md # separating read (query) from write (command) models
├── data-analysis.md # analytical reasoning: question, method, evidence, confidence
├── data-engineering.md # data quality, lineage, grain; blocks unsound conclusions
├── ddd.md # domain modeling: boundaries, aggregates, consistency
├── design-patterns.md # patterns that help vs. hurt (Java/Spring)
├── event-driven.md # event-driven style: event design, coupling, schema evolution, topology
├── model-and-effort-economy.md # (meta) right-size model/effort/window/fan-out to task; cost vs. correctness
├── observability.md # operability: structured logs, metric cardinality, trace propagation, alertable signals
├── reporting.md # (output) final shaping stage: narrative + HTML from a validated analysis
├── saga.md # cross-service consistency without distributed transactions
├── security.md # app-sec: injection, authz/IDOR, secrets & PII-in-log, crypto, dangerous sinks
├── solid.md # responsibility, substitutability & dependency direction of changed code
├── spring-production-readiness.md # runtime risk: timeouts, idempotency, transactions, concurrency, leaks
└── testing.md # test quality: does a test fail for the right reason?
rules/
├── analysis-rigor.md # report rigor gate: conclusions must be sustained by evidence
├── severity-rubric.md # global review rubric (MUST/SHOULD/NIT/NO_COMMENT)
└── spec-rubric.md # global spec-quality rubric (BLOCKER/SHOULD/NIT/OK)
templates/
├── reports/ # HTML report templates, one per situation
│ ├── analytical.html # diagnostic analysis (usage/cost across envs)
│ ├── metric-trend.html # a quantity over time
│ ├── discovery-stories.html # docs -> epics/stories/trilha
│ └── exec-summary.html # decision-first summary for management
├── themes/ # neutral CSS-variable theme presets (skins) — no brand
│ ├── theme-slate.css # light
│ └── theme-dark.css # dark
├── THEMING.md # the theme-variable contract + how to add a theme
├── adr.md # architecture decision record format (architecture-decision-records skill)
├── analysis-spec.md # intermediate analytical contract (the HTML derives from it)
└── spec.md # prescriptive engineering-spec format
skills/
├── architecture-decision-records/
│ └── SKILL.md # construction: record WHY a hard-to-reverse decision was made (immutable, superseded not edited)
├── architecture-review/
│ └── SKILL.md # review: a Java/Spring design at system altitude
├── claude-setup-audit/
│ └── SKILL.md # (meta) audit & fix a Claude Code .claude/ setup
├── effort-budget/
│ └── SKILL.md # (meta) right-size model/effort/window/fan-out under a token/cost budget
├── eval-harness/
│ └── SKILL.md # (meta/quality) measure non-deterministic outputs (LLM/agent/classifier): dataset + grader + baseline
├── java-pr-review/
│ └── SKILL.md # review: a Java/Spring PR diff
├── report/
│ └── SKILL.md # construction: understand -> validate data -> analyze -> HTML report
├── retrospective/
│ └── SKILL.md # (meta) turn a lesson / repeated mistake into a durable config change
├── skill-author/
│ └── SKILL.md # (meta) scaffold a new skill/lens/rule correctly (or decide not to add one)
└── spec-author/
└── SKILL.md # construction: write a prescriptive spec for a change
examples/
└── reporting/ # behavioral-eval fixtures for report + EXPECTED.md
scripts/
├── sanitization-check.sh # deterministic sanitization gate (CI + pre-commit hook)
└── repo-integrity-check.sh # structural-integrity gate: index sync, frontmatter, links, release marker
.github/workflows/
├── sanitization.yml # CI: sanitization gate + gitleaks
└── integrity.yml # CI: repo structural-integrity gate
LICENSE # CC BY 4.0
VERSION # current release (semver), machine-readable
CHANGELOG.md # what changed per release — the "new patch" signal
Skills (by type of work) and lenses (by subject) are added the same way as the repo grows — never a giant do-everything skill. If a skill ever needs to ship standalone, a packaging/export step copies the lenses it references into the skill so it stays self-contained.
Using a lens
The lenses are written for the skills to consult, but they double as human-readable checklists
you can paste into a review. Point Claude Code at a diff or PR and ask it to review using
java-pr-review, or at a design or architectural change and ask for architecture-review; the
skill loads the rubric and the relevant lenses, then emits severity-tagged findings.
Sanitization & copyright policy
This repository contains only original material written from general, common engineering knowledge. It reproduces no book text, examples, code, didactic structure, or identifiers from any source. Where study material informed a lens, it was read as temporary input and distilled into original heuristics, review questions, and synthetic examples — never paraphrased or transcribed.
- No copyrighted material is committed. PDFs, EPUBs, and raw study notes are
.gitignored. - No corporate material is committed. No real code, service names, business rules, endpoints, logs, payloads, secrets, tokens, or certificates.
- All examples are synthetic and domain-neutral —
Order,Payment,Notification,Report,Customer,Invoiceand similar — with no relation to any real system.
Documentation
- docs/SANITIZATION_POLICY.md — the full sanitization rules, clean-room authoring process, and pre-commit checklist (the section above is the short version).
- docs/CORPORATE_ADOPTION.md — a ready-to-use prompt for a Claude Code instance inside a corporate environment to read this sanitized reference and bootstrap an internal version behind the corporate sanitization gate. No corporate content lives here.
- docs/field-notes-verification-and-agentic-harness.md — sanitized field notes distilled from a real generation-and-verification project: the proof harness, the decision oracle / delegated autonomy, and the agentic operating system. Seeds for future lenses/skills.
Roadmap
Lenses and skills grow by real need, never speculatively. Planned next, in rough order:
- Lenses: the review/architecture set landed
security,observability, andevent-drivenin v0.6.0; further lenses are added only when a real consumer needs one (no speculative additions). - Review skills:
architecture-reviewconsumes the architecture/quality lenses (ddd,saga,cqrs,cdc,event-driven,security,observability);java-pr-reviewaddssecurityandobservabilityat line/method level. - Construction skills:
spec-author,report(a data-engineering + data-analysis pipeline that validates the data, runs the analysis, and only then renders an HTML report whose conclusions are sustained by evidence), andarchitecture-decision-records(records why a hard-to-reverse, cross-cutting decision was made — context, alternatives, consequences — immutable and superseded rather than edited) today;feature-build(spec → Java/Spring code) andapp-bootstrap(scaffold a service or module) as they land — all reusing the lenses generatively. - Meta/ops skills:
claude-setup-audit(audits & fixes the.claude/setup against theagent-skillslens),retrospective(turns a lesson or a repeated mistake into a durable config change — hook / rule / CLAUDE.md / memory — so it does not recur),effort-budget(right-sizes model/effort/window/fan-out under a token/cost budget),eval-harness(measures non-deterministic outputs — an LLM feature, agent, or classifier — against a versioned dataset and a baseline, so a regression is caught before release), andskill-author(scaffolds a new skill/lens/rule correctly — or decides one isn't warranted — keeping the indexes in sync) today.
A lens is added only when a real consumer needs it; a skill is added per type of work.
Versioning & patches
Releases are versioned (VERSION), recorded in CHANGELOG.md, and tagged in
git (vX.Y.Z). A newer tag than the one a CLI last absorbed is the signal that a new patch is
available: tell it "saiu o novo patch" (or "learn what changed") and it reads only the changelog
delta and updates what it knows — instead of re-reading the whole repo. See the patch update path in
CLAUDE.md.
License
Licensed under Creative Commons Attribution 4.0 International (CC BY 4.0) — share and adapt freely, including commercially, with attribution.
Contributing rules
- No PDFs, EPUBs, books, or copyrighted excerpts.
- No secrets, credentials, certificates, real logs, real payloads, or corporate code.
- Synthetic, neutral examples only.
- Every rule must state a concrete consequence; if it can't, it's a
NITorNO_COMMENT. - Keep architecture rules separate from style preferences.