convez.ai
MCP Server
marcoguillermaz

claude-dev-kit

marcoguillermaz/claude-dev-kit

Ver no GitHub
BomPluginScore · de 0 a 100

Scaffold for legible, reviewable AI-assisted development. Turn Claude Code into a reviewable collaborator with tiered pipelines, 24 audit skills, 11 stacks, MCP server, and Anthropic drift tracking.

Instalação

$npx convez-ai marcoguillermaz/claude-dev-kit

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
4
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 3 dias
Versão
v2.3.4
Issues abertas
29
Contribuidores
4

README

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

claude-dev-kit

npm version License: MIT Node.js >= 22 CI OpenSSF Scorecard

Scaffold for legible, reviewable AI-assisted development. Claude generates. Your team decides. MCP-native — read CDK governance state from Claude Desktop, ChatGPT, Cursor, VS Code.

Claude Code is a powerful CLI that reads, writes, and reasons about your entire codebase. Without shared process, it makes autonomous decisions that are hard to track and harder to review.

claude-dev-kit scaffolds a structured, reviewable development process on top of Claude Code. It enforces one non-negotiable rule mechanically: Claude cannot declare a task complete until your tests pass. Everything else scales with your needs.

Since v1.17.0, CDK ships an MCP server alongside the CLI. Any MCP-aware client can read your project's doctor report, team-settings policy, last arch-audit, and skill inventory without anyone running the CDK CLI. See MCP server.


Quick Start

npx mg-claude-dev-kit init

The wizard detects your project state and guides you through setup. Three paths available:

PathUse when
Existing projectAdd structure to a project that already has code
New projectStarting from scratch
From existing docsShare repos or docs - Claude reads them and populates everything

After init, open Claude Code and start working. The scaffold is active immediately.

Context Builder (v1.27.0)

Run context before init if you want the scaffold to come out the same way every time, with a written record of what you asked for:

npx mg-claude-dev-kit context                       # produces CONTEXT.md
npx mg-claude-dev-kit init                          # reads CONTEXT.md, scaffolds with no further prompts
npx mg-claude-dev-kit context --all                 # one-shot: context then init
npx mg-claude-dev-kit context --from-yaml file.md   # bypass interview, validate + copy
npx mg-claude-dev-kit validate-context              # CI gate: exit 0/1 on schema check

CONTEXT.md is a schema-validated project context file. Greenfield runs a PM-friendly interview. Existing repos go through three-phase inference: algorithmic detection, LLM extraction, hybrid PM review. The first question routes you to a PM or developer flow. The developer flow reuses the technical questions from the legacy init wizards (projectName, stack, commands, scaffold options) and auto-derives tier.rationale from team size + work scope, so devs are not asked to write PM rationale prose.

As of v1.27.0, the schema covers all four pipeline tiers: tier 0 (Discovery) and tier S (Fast Lane) for solo or bugfix work, tier M (Standard) for feature-block work with feature flags (has_api, has_database, has_frontend, has_design_system, has_prd), and tier L (Full) for complex domain projects.


What it does

Tiered pipelines matched to risk

TierPipelineBest for
0 - DiscoveryStop hook onlyFirst exploration - zero process
S - Fast Lane4 steps, scope-confirmSingle dev, low risk, quick fixes
M - Standard8 phases, 2 STOP gatesFeature blocks, 1-2 collaborators
L - Full14 phases, 4 STOP gatesTeam projects, complex domain changes

Start at Tier 0. Move up when you need more structure: npx mg-claude-dev-kit upgrade --tier=m

24 audit skills

Executable multi-step programs that run inside Claude Code. Not prompt instructions - structured audit workflows with model routing (haiku for mechanical checks, sonnet for analysis).

SkillTiersPurpose
/arch-auditS M LGovernance files vs Anthropic docs. Auto-fixes deprecations.
/security-auditS M LAuth, input validation, RLS, CVE scan. 3-path: WEB / NATIVE / HYBRID. MCP-aware (v1.20+): Step 3c queries mcp-nvd server for live CVE data with local audit fallback.
/perf-auditS M LBundle size, serial awaits, query efficiency. 8-stack patterns.
/skill-devS M LCoupling, duplication, dead code, debt-density. Step 3b (v1.22+): hotspot priority via churn × debt — top-10 ranked by 4-quadrant matrix using git log --since="6.months.ago".
/simplifyS M LEarly returns, nesting, dead code. Applies changes directly.
/commitS M LConventional Commits - auto-detects type, scope, description.
/api-designM LURL naming, HTTP verbs, response envelope, pagination.
/skill-dbM LSchema normalization, indexes, N+1 queries, RLS.
/migration-auditM LStack-aware migration safety: data loss, rollback, lock-heavy DDL. Prisma/Drizzle/Supabase/SQL.
/visual-auditM LTypography, spacing, hierarchy, dark-mode, micro-polish.
/ux-auditM LISO 9241-11, Nielsen heuristics, user confidence.
/responsive-auditM LLayout at 320-1024px, tap targets, WCAG.
/ui-auditM LDesign token compliance, component adoption, empty states.
/accessibility-auditM Laxe-core WCAG 2.2, APCA contrast, static a11y (aria, tabindex, focus, labels).
/test-auditM LCoverage (lcov/Istanbul/Cobertura/go/tarpaulin/xcresult), pyramid shape, anti-patterns (.only, skipped, empty, no-assertion, sleeps).
/doc-auditM LDoc drift: link resolution, code-block syntax (json/yaml/toml), CDK placeholder residuals, slash-command name match, skill-count consistency, ADR freshness, stack-sync (Next.js/Django/Swift).
/api-contract-auditM LOpenAPI contract drift (endpoints, schemas, status), breaking-change detection vs previous spec, versioning consistency, security scheme alignment, Richardson Maturity L0-L3 scoring. Auto-gen for FastAPI / NestJS / Express+swagger-jsdoc / Next.js route handlers / Django REST.
/infra-auditM LInfrastructure security across GitHub Actions (pwn-request, secret logging, pinning, permissions), Dockerfile (root, latest tag, URL add), K8s (runAsNonRoot, privileged, hostNetwork), Terraform (IAM wildcards, state in git), GitLab CI. Stack-agnostic.
/compliance-auditM LGDPR profile: data-subject rights (delete, export, rectify), consent, lawful basis, PII identification, encryption-at-rest on special-category, logging hygiene, retention, sub-processors. SOC 2 / HIPAA scaffolded for v1.15+.
/dependency-auditM LOutdated package audit: Tier A (safe batch) / B (non-core major) / C (core/breaking-risk) classification, changelog summary for Tier B/C, codebase impact grep, runtime LTS status. Stack-aware (node-ts/python/swift); agnostic fallback for other stacks. Audit-only in v1; mutating apply-tier-a deferred to Q4. MCP-aware (v1.20+): Step 2 queries package-registry-mcp for multi-ecosystem package metadata with WebFetch fallback.
/pr-reviewM LAutonomous local PR review via gh CLI: spawns review subagent on the diff, classifies findings (Critical / Major / Minor) using universal + stack-specific severity criteria, posts review as PR comment for audit trail. Configurable via team-settings.json prReviewSeverity. Read-only. --deep escalates to opus for sensitive changes. Also exposed as cdk_pr_review MCP tool.
/skill-reviewM LQuality review pipeline for skill portfolios. Spec compliance, cross-tier coherence, behavioral fixtures.
/dependency-scanM LPipeline-integrated (Phase 1): forked-context scan that returns the full file list — routes, components, shared types, DB tables — fed into the Phase 1 STOP gate. Six structurally independent checks (C1–C6) with a "Mandatory additions" section.
/context-reviewLPipeline-integrated (Phase 8.5): forked-context review that runs after block closure to recompact CLAUDE.md and detect context drift before the next block opens. Tier L only.

Skills are conditionally installed based on your project: hasApi, hasDatabase, hasFrontend, hasDesignSystem.

11 tech stacks auto-detected

Node.js/TS, Node.js/JS, Python, Go, Swift, Kotlin, Rust, .NET, Ruby, Java - plus generic fallback. Security rules, permissions, and CLAUDE.md fields adapt automatically.

MCP server (v1.17.0+)

The mg-claude-dev-kit package ships an MCP server (claude-dev-kit-mcp binary) alongside the CLI, version-locked, single npm install -g. Any MCP-aware client (Claude Desktop, ChatGPT desktop, Cursor, VS Code, Copilot Studio) can query CDK governance state without the CDK CLI running. Six read-only tools cover doctor report, team-settings, last arch-audit, skill inventory, package metadata, and /pr-review comments. Full reference in the MCP server section below.

Incremental adoption

Install individual components without a full scaffold:

npx mg-claude-dev-kit add skill security-audit   # install one skill
npx mg-claude-dev-kit add rule git                # install one rule
npx mg-claude-dev-kit add rule security --stack swift  # stack-specific variant

Custom skills (custom-* prefix) are preserved across upgrades. See Custom Skills Guide.


Architecture

your-project/
├── CLAUDE.md                    # Project context (<200 lines)
├── .claude/
│   ├── settings.json            # Permissions + Stop hook (mechanical enforcement)
│   ├── team-settings.json       # Team policy: minTier / allowed / blocked / required (v1.16+)
│   ├── rules/
│   │   ├── pipeline.md          # Development workflow (tier-appropriate)
│   │   ├── security.md          # Stack-aware: web / apple / android / systems
│   │   ├── git.md               # Commit format, branch rules
│   │   └── output-style.md      # Communication rules
│   ├── skills/                  # Audit skills (conditional per project)
│   ├── session/                 # Session recovery (gitignored)
│   └── .mcp.json                # Wire claude-dev-kit-mcp into MCP-aware clients (v1.17+)
├── docs/                        # Requirements, specs, backlog (M/L)
├── .github/                     # PR template, CODEOWNERS
└── .pre-commit-config.yaml      # Secret scanning

The Stop hook in settings.json is the core enforcement mechanism. It blocks Claude from completing any task until tests pass. Present in every tier, including Discovery.


CLI Commands

npx mg-claude-dev-kit init                    # scaffold wizard
npx mg-claude-dev-kit init --dry-run          # preview without writing
npx mg-claude-dev-kit init --answers file.json  # skip prompts (CI/automation)
npx mg-claude-dev-kit doctor                  # validate setup (29 checks)
npx mg-claude-dev-kit doctor --report         # JSON output for CI
npx mg-claude-dev-kit doctor --ci             # silent, exit 1 on failure
npx mg-claude-dev-kit upgrade                 # update template files
npx mg-claude-dev-kit upgrade --tier=m        # promote to higher tier
npx mg-claude-dev-kit upgrade --anthropic     # show diff for Anthropic-influenced files (dry-run)
npx mg-claude-dev-kit upgrade --anthropic --apply  # write the diff (with .bak backup)
npx mg-claude-dev-kit add skill <name>        # install one skill
npx mg-claude-dev-kit add rule <name>         # install one rule
npx mg-claude-dev-kit new skill               # create a custom skill (wizard)
claude-dev-kit-mcp                            # MCP server (stdio); wire from .mcp.json

MCP server

claude-dev-kit-mcp is a Model Context Protocol server that exposes CDK governance signals to any MCP-aware client (Claude Desktop, ChatGPT desktop, Cursor, VS Code, Copilot Studio). The CLI and MCP server ship in the same npm package, version-locked.

Wire it up by adding to .mcp.json (project-scoped) or ~/.claude/.mcp.json (user-scoped):

{
  "mcpServers": {
    "cdk": { "command": "claude-dev-kit-mcp" }
  }
}

Read-only tools exposed:

ToolReturns
cdk_doctor_reportdoctor --report JSON (29 checks)
cdk_team_settingsparsed .claude/team-settings.json
cdk_arch_audit_statuslast arch-audit run timestamp + age
cdk_skill_inventoryinstalled skills + frontmatter snapshot
cdk_package_metaCDK package name, version, CLI path, cwd
cdk_pr_reviewreads existing /pr-review skill comments on a GitHub PR (verdict, severity counts). Read-only — to generate a fresh review, invoke the /pr-review CDK skill.

The server resolves the project root from $CDK_PROJECT_ROOT if set, otherwise from process.cwd(). v1.17.0 launched read-only by design; that posture is unchanged through v1.30.0.


Process controls

Stop hook (every tier) - Claude cannot declare done until tests pass:

"Stop": [{ "hooks": [{ "type": "command",
  "command": "npm test || echo '{\"decision\": \"block\", \"reason\": \"Tests must pass.\"}'"
}] }]

STOP gates (Tier M/L) - Requirements reviewed before implementation. Spec-first or scope-confirm mode auto-selected per block.

Audit logging - Every tool use appended to ~/.claude/audit/project.jsonl.

AI attribution - Every Claude-assisted commit tagged with Co-authored-by.

Weekly arch-audit - SessionStart hook checks if /arch-audit ran in the last 7 days.

CODEOWNERS - Changes to .claude/ require tech lead review.


Testing

node packages/cli/test/integration/run.js    # 1132 integration checks
node --test 'packages/cli/test/unit/**/*.test.js'   # 585 unit tests

Covers: file structure per tier, Stop hook presence, pipeline gate counts, placeholder resolution, skill pruning, security variant selection, native stack adaptation, rubric scoring, cross-stack content invariants (10 stacks — the named stacks excluding the other fallback), golden-file assertions (Swift, Node-TS, Python), full CLI execution via --answers fixtures.

A separate template-coverage layer (under packages/cli/test/template-coverage/) hard-fails on cross-tier semantic drift, missing gate clauses, and undocumented placeholders in the shipped templates. The three scripts (cross-tier-lint.mjs, gate-enum.mjs, placeholder-check.mjs) run standalone for local work and automatically inside run.js. Strategy and concept registry: docs/architecture/test-coverage-strategy.md.


Requirements


Documentation

DocumentAudienceContent
Operational GuideTeams adopting CDKFull reference: installation, tiers, workflow, governance, FAQ
Custom Skills GuideDevelopers extending CDKSKILL.md format, frontmatter schema, authoring patterns
Product BriefStakeholdersStrategic positioning, target users, scope
Quality RubricTeams evaluating workspaces8-dimension scoring (D1-D8, 0-100%)

Roadmap

See GitHub Milestones for the 12-month plan.

Current: v1.30.0 ships the VS Code extension (P1–P3): governance tree view with skill and rule browsing, live health status bar with arch-audit staleness, and CDK doctor findings surfaced as Problems panel diagnostics. Also adds /skill-security (SkillSpector integration, tier S+), a 64-pattern vulnerability scanner for Claude Code skill files. Carried forward: v1.29.x cross-LLM rubric automation for Context Builder, v1.28.0's skill-review pipeline P3 robustness, v1.27.0's Context Builder v1.1 cycle, v1.22.0's /skill-dev v2 hotspot step, v1.21.0's PreToolUse runtime enforcement, and v1.20.0's MCP-aware audit skills.

Next: /arch-audit MCP-aware once the upstream Anthropic spec MCP server lands. /privacy-audit re-eval (Issue #97 sub-track 3) when AST tracing matures or demand signal materializes. Q2 #3 VitePress docs site (ICE 432) stays on hold.


Contributing

See CONTRIBUTING.md for development setup, project structure, and PR guidelines.

To report a security issue, see SECURITY.md.

License

MIT


Built and maintained by Marco Guillermaz. Distributed on npm as mg-claude-dev-kit. Discussions and questions: GitHub Discussions.

Ver o original no GitHub

Bom para

Relacionados