alfaiate

/aw.faj.ˈa.tʃi/ · noun, Portuguese · a tailor

The Claude Code scaffolder that interviews you.

Twelve questions. One shell-out to your own claude CLI. A tailored CLAUDE.md with your stack verbatim, custom path-scoped rules encoding your red lines, and a prioritized skill list — written on top of an opinionated base template (4 agents, 8 skills, 5 rules, 4 hooks, 7 stack overlays, under-80-line CLAUDE.md, zero runtime dependencies).

Off-the-rack templates are generic. Yours shouldn't be.

This is a distillation of patterns used across several production Claude Code projects. If you try it and something feels off, open an issue.

Quick start · Why · What you get · Architecture · CLI · Sponsor

Quick start

# Fast path (static templates):
npx alfaiate my-app

# Smart path (interviews you, uses your own claude CLI):
npx alfaiate my-app --smart

That's it. Answer a few prompts — three for the static path, twelve for --smart — and your project is ready.

  alfaiate  /aw.faj.ˈa.tʃi/  noun, Portuguese — a tailor
  The Claude Code scaffolder that interviews you. Zero deps.

? Project name (my-app) my-app
? Package name (for imports / modules) (my_app) my_app

  Stack
    1) Python — FastAPI + uv + SQLAlchemy
    2) Python — Django + DRF + Postgres + Celery
    3) TypeScript — Next.js + pnpm + Prisma
    4) Node — Fastify + Drizzle + Postgres + Vitest
    5) Go — chi + sqlc + pgx + slog
    6) Rust — axum + sqlx + tokio + tracing
    7) AWS Lambda (Python) — SAM + DynamoDB single-table
    8) None — base template only
? Choose 1-8 (8) 1
? Install OpenWolf (npm i -g openwolf && openwolf init)? [y/N] y

  Scaffolding my-app
  → /Users/you/code/my-app

  ✓ copying base template
  ✓ applying overlay: python-fastapi
  ✓ replacing placeholders
  ✓ initialized git repository

  Done.

  Next steps:
    cd my-app
    uv sync
    claude

Why

Every new project wastes hours re-configuring Claude Code: hooks, permissions, agents, skills, rules. And most community templates swing hard the other way — shipping 100+ agents and 200-line CLAUDE.md files that exceed working-memory budgets and get partially ignored.

This scaffolder picks a deliberately small surface: the fewest pieces needed for a serious Claude Code setup, with every piece chosen because you'd reach for it on almost any project.

What you actually get, measured

| Metric | Value | |:--------------------------------|:--------------------------------------| | Root CLAUDE.md line count | ≤ 80 lines (enforced in CI) | | Agents shipped | 4 (architect, reviewer, test-analyzer, researcher) | | Skills shipped | 8 | | Path-scoped rules | 5 (python, typescript, tests, git, hooks) | | Enforcement hooks | 2 (format-on-write, block push to main) | | Observability hooks | 2 (repeated-read warning, token ledger) | | Stack overlays | 7 (python-fastapi, python-django, typescript-nextjs, node-fastify, go-chi, rust-axum, aws-lambda-sam) | | Runtime dependencies | 0 | | Node version | 18+ | | Scaffold time on my M1 | < 1 second (without OpenWolf) | | License | MIT |

All of the above are facts about the scaffolded output, verifiable by running npx alfaiate my-test-app -y and inspecting what lands on disk. No handwavy token-reduction claims — you can measure those yourself if you care.

Who this is for (and who it isn't)

Good fit if you:

• Want a Claude Code project running in under 2 minutes without reading docs.
• Prefer 8 well-chosen skills over 50 mediocre ones.
• Believe CLAUDE.md should be short enough to stay in working memory.
• Want hooks that enforce rules, not instructions the model may ignore.
• Are on Python (FastAPI or Django), TypeScript (Next.js or Fastify), Go, Rust, or AWS Lambda — the seven shipped overlays.

Bad fit if you:

• Want the biggest possible catalog of agents/skills/commands to browse and pick from — use claude-code-templates (by davila7) and its web catalog at aitmpl.com.
• Need Rails / Elixir / Phoenix / Svelte overlays right now — open an issue or, better, a PR. They aren't in the box yet.
• Want a framework that does orchestration across many sub-agents — look at claude-flow or similar.

This is a scaffolder with taste, not a catalog. If you disagree with the taste, the project is MIT-licensed — fork, remix, ship.

Why this vs. BMAD / SpecKit / OpenSpec / GSD / Superpowers

Those are runtime operational frameworks — they stay in the loop while you work, orchestrating multi-step workflows, specs, and state. alfaiate is a one-shot scaffolder: it drops a small, opinionated .claude/ layout into a fresh repo and then gets out of the way. The two categories are complementary, not competing — you can run any of those frameworks on top of a alfaiate-scaffolded project.

Mental model: create-next-app, not next.js. If you're shopping for a runtime agentic framework, this isn't one. If you're shopping for a production-ready starting layout you can have in 2 minutes, this is it.

What you get

| Agent | Model | Can write? | Role | |:-----------------|:-------|:-----------|:-----| | architect | Opus | no | Plan mode. Designs and reviews, never implements. | | code-reviewer | Opus | no | Full-file review, 0–100 score, blockers vs suggestions. | | test-analyzer | Sonnet | no | Runs the suite, finds coverage gaps. | | researcher | Sonnet | no | Forked context. Deep exploration without polluting the main session. |

| Skill | What it does | |:---------------------|:-------------| | project-memory | Persistent memory across sessions via docs/project-notes/. | | implement | 4-phase workflow: explore → plan → code → verify → document. | | review | Diff-aware review with 0–100 scoring. | | commit-and-pr | Atomic conventional commits + PR template. | | python-patterns | uv, beartype, stamina, glom, structlog, Result. | | typescript-patterns| Strict TS, Zod, neverthrow, pino, pnpm. | | aws-serverless | Lambda ARM, HTTP API, DynamoDB single-table, SAM. | | api-design | Additive payloads, dispatch maps, FSM, cursor pagination. |

| Rule | Globs | |:-----------------|:------| | python.md | **/*.py, pyproject.toml | | typescript.md | **/*.ts, **/*.tsx, tsconfig.json | | tests.md | tests/**/*, **/*.test.*, **/*.spec.* | | git.md | **/* | | hooks.md | .claude/settings.json, .claude/hooks/** |

Enforcement (block on violation)

• Post-write — auto-format every file Claude touches (ruff format for Python, prettier for TS).
• Pre-bash — block git push to main/master; force PRs.

Observability (warn, never block — zero runtime deps, pure Node stdlib)

• Pre-read — .claude/hooks/pre-read-warn.js warns on stderr if the same file is read twice within a 30-minute window, so you notice re-reads instead of silently burning tokens on them.
• Post-read — .claude/hooks/post-read-ledger.js appends a JSONL line with {timestamp, file, bytes, estimated_tokens} to .claude/.token-ledger.jsonl, giving you a grep-able local usage history.

Hooks follow a strict doctrine — warn never block, under 5 seconds, no network, no AI, zero runtime dependencies. The full rules live in template/base/.claude/rules/hooks.md (same file you'll find at .claude/rules/hooks.md after scaffolding).

Hooks run deterministically, unlike instructions in CLAUDE.md which land at roughly 70% compliance.

| Overlay | Highlights | |:---------------------|:-----------| | python-fastapi | uv + FastAPI + async SQLAlchemy + Alembic | | python-django | uv + Django + DRF + Postgres + Celery + drf-spectacular | | typescript-nextjs | pnpm + Next.js + Prisma + strict TS | | node-fastify | pnpm + Fastify + Drizzle + Postgres + Vitest (backend-only TS) | | go-chi | chi router + sqlc + pgx v5 + slog + golangci-lint | | rust-axum | axum + sqlx + tokio + tracing + clippy-deny-warnings | | aws-lambda-sam | Python SAM + Lambda ARM (Graviton2) + DynamoDB single-table |

Architecture — progressive disclosure

Every layer is loaded lazily. CLAUDE.md stays under the ~500-token working-memory budget; everything else is pulled in only when relevant. This is the core design principle — fewer tokens in working memory means higher instruction compliance.

  +-----------------------------------------------+
  |  CLAUDE.md  (<80 lines — always in context)   |   Layer 1: Essentials
  +-----------------------------------------------+
                        |
                        v
  +-----------------------------------------------+
  |  .claude/rules/   (path-scoped via globs)     |   Layer 2: Rules
  |  python  typescript  tests  git  hooks       |   loaded when files match
  +-----------------------------------------------+
                        |
                        v
  +-----------------------------------------------+
  |  .claude/skills/  (on-demand workflows)       |   Layer 3: Skills
  |  implement  review  commit-and-pr  ...        |   loaded when invoked
  +-----------------------------------------------+
                        |
                        v
  +-----------------------------------------------+
  |  .claude/agents/  (isolated contexts)         |   Layer 4: Agents
  |  architect  code-reviewer  test-analyzer ...  |   forked main context
  +-----------------------------------------------+

Persistent memory lives in docs/project-notes/ (git-tracked). See examples/project-notes-real/ for a filled-in example of what these files look like after a few weeks of real work — empty templates don't make the value obvious. Optional third-party integrations can add their own layer on top — see Optional integrations below.

Optional integrations

The scaffolder stays intentionally small. If you want extra intelligence, you can layer third-party tools on top. The CLI ships one such integration as an optional prompt, not a requirement.

OpenWolf (opt-in at scaffold time)

OpenWolf is a community middleware for Claude Code that adds a .wolf/ directory with a file-anatomy map, learning memory (cerebrum.md), a token ledger, and six lifecycle hooks. Its maintainer reports substantial token reductions on their own projects.

If you answer "yes" to the OpenWolf prompt in the CLI, the scaffolder runs:

npm install -g openwolf
openwolf init

You can also install it later, manually, on an already-scaffolded project. This boilerplate's hooks (format-on-write, block push to main) coexist cleanly with OpenWolf's hooks — the two serve different purposes.

Honesty note: OpenWolf is young (launched March 2026) and single-maintainer at time of writing. The integration is offered because it's a neat complement, but alfaiate does not depend on it and works fully without it. Evaluate OpenWolf on its own terms before adopting it.

CLI reference

npx alfaiate <project-dir> [flags]

Flags:
  -y, --yes                 Skip prompts and use defaults
      --name <name>         Project name (default: target directory basename)
      --stack <stack>       python-fastapi | typescript-nextjs | aws-lambda-sam
      --openwolf            Install OpenWolf globally and run `openwolf init`
      --smart               Generate a tailored CLAUDE.md via the local `claude` CLI
  -h, --help                Show help
  -v, --version             Show CLI version

Smart mode (opt-in)

Run with --smart to turn the scaffolder into a 2-minute onboarding agent instead of a template copier:

npx alfaiate my-app --smart

What it produces, beyond the base + overlay copy:

1. A tailored CLAUDE.md — the Essential commands section reflects your stack verbatim, the Never section bakes your red lines in literally, and the Architecture section cites the best-practices bullets that shaped it.
2. 1–3 custom .claude/rules/<name>.md files — path-scoped rules that encode the conventions you gave during discovery (e.g. a migrations.md rule with globs: alembic/versions/** if you said "never touch migrations without review").
3. A prioritized skill recommendation list at .claude/smart-skills.md — the eight shipped skills ranked as critical / recommended / optional with a one-line reason each.
4. Additive .claude/settings.json overrides — new permissions or hooks unioned into the base (model, apiKeyHelper, env, attribution are stripped by the runtime and cannot be touched).
5. Follow-up questions at the end of the run, for things the 12 discovery questions did not cover but that would meaningfully refine the output.
6. A rationale at .claude/smart-rationale.md citing the specific discovery answers and best-practices themes that shaped the biggest decisions.

The questionnaire is 12 questions (English or Portuguese, auto-detected from your shell $LANG / $LANGUAGE) covering project objective, stack, runtime, team size, testing philosophy, git workflow, red lines, mandatory conventions, past pain points, and cost sensitivity.

Under the hood, the CLI shells out to:

claude -p --output-format json --json-schema <schema> \
  --system-prompt <system> --max-budget-usd 1.00 --model opus <prompt>

Requirements. The claude CLI must be on your PATH and already authenticated (npm i -g @anthropic-ai/claude-code && claude auth login). Smart mode runs under your existing Claude Code subscription, so there is no extra billing.

Fail-soft. If claude is missing, times out, returns malformed JSON, or is interrupted, the scaffold is left valid (base + overlay) and your answers are dumped to .claude/smart-answers.json for retry.

Not available with --yes. Smart mode needs an interactive terminal for the questionnaire.

Non-interactive example (CI / scripts):

npx alfaiate my-app \
  --yes \
  --stack python-fastapi \
  --name my-app \
  --openwolf

Requirements: Node 18 or newer. Zero runtime dependencies.

Customization after scaffolding

1. Commands — edit the top of CLAUDE.md if your build/test/lint differs.
2. Permissions — edit .claude/settings.json permissions.allow / deny.
3. Rules — add files to .claude/rules/ with a globs: frontmatter.
4. Skills — drop folders into .claude/skills/ with a SKILL.md.
5. Agents — add .md files to .claude/agents/ with model: and tools: frontmatter.
6. Hooks — read .claude/rules/hooks.md before adding any. Minimum bar: warn never block, under 5 seconds, no network, no AI, zero runtime dependencies.

Settings precedence

Claude Code reads settings from three places, in this order (later overrides earlier):

| Scope | Path | Committed? | |:------------|:---------------------------------------|:-----------| | User | ~/.claude/settings.json | no (personal) | | Project | <repo>/.claude/settings.json | yes (shared) | | Local | <repo>/.claude/settings.local.json | no (git-ignored) |

The scaffolder writes Project settings only. Put personal preferences (preferred model, extra MCP servers, your own hook paths) in settings.local.json or ~/.claude/settings.json — never commit them, and never put anything the whole team needs there (it should live in Project scope).

Local development of the CLI itself

git clone https://github.com/yannoliveira/alfaiate.git
cd alfaiate
node bin/cli.js /tmp/test-app -y               # run the CLI directly
node bin/cli.js /tmp/test-py -y --stack python-fastapi
npm pack                                       # build a tarball

No runtime dependencies — plain Node 18 with fs, path, readline, and child_process. Templates live in template/base/ (always copied) and template/overlays/<stack>/ (applied on top when a stack is chosen).

Sponsor

This project is free, MIT-licensed, and maintained in my free time. If it saves you hours on your next project, consider sponsoring — it keeps the updates coming and directly funds new overlays, skills, and docs.

Brazilian? Pix works too — scan or copy the key from the sponsors page.

Every sponsor gets their name (or company logo) listed below. Corporate sponsors get priority review on feature requests and direct Slack/Discord access.

Philosophy and credits

This CLI is an opinionated synthesis of the best public work on Claude Code. Every idea here is credited — read the originals, they are better than this README.

• Boris Cherny (Anthropic) — 5 parallel worktrees, keeping CLAUDE.md near 2.5K tokens, plan mode + Opus for hard problems, verification loops (2–3× quality), the /commit-push-pr pattern.
• OpenWolf by Cytostack — 6 hooks, anatomy
  • cerebrum + memory, ~65% token reduction, mandatory Prevention field in buglog.
• ClaudeForge — progressive disclosure (−70% tokens), dispatch maps, two-tier validation, 0–100 review scoring, additive-only merge.
• Harness Engineering — single-threaded loop, 18-tool dispatch map, three-layer context compression, multi-agent worktrees.
• Anthropic official docs — CLAUDE.md, Hooks, Skills, Sub-agents, Agent Skills.
• shanraisshan/claude-code-best-practice
• awesome-claude-code by hesreallyhim

Contributing

PRs welcome. Start here:

• CONTRIBUTING.md — full contribution guide, including how to add new skills, rules, agents, and stack overlays.
• CODE_OF_CONDUCT.md — be kind, assume good faith.
• SECURITY.md — how to report vulnerabilities privately.
• MAINTAINERS.md — release process and branch-protection setup (maintainer only).

Quick summary of the rules:

• Keep additions additive — never remove working patterns without a deprecation path.
• Keep the scaffolded CLAUDE.md under 80 lines.
• Document every new rule / skill / agent in the README tables.
• Run the smoke tests before opening a PR.
• Follow Conventional Commits (feat:, fix:, docs:, refactor:, chore:).

See open issues for things to pick up, or filter by the good first issue label if you're new to the project.

License

MIT — see LICENSE.

If this helped you, please give it a star — it genuinely helps others find the project.