Baseline

A clone-and-go, full-stack Next.js starter with a built-in spec-driven AI development team and AWS-native FinOps. Fork it (or "Use this template") and you start every project with auth, payments, email, a database, a design system, i18n, testing, CI, Infrastructure-as-Code, and cloud-cost governance already wired — plus a set of Claude Code agents and slash commands that run a disciplined spec → design → build → verify workflow.

Not just a code template. The .claude/ directory ships a team of specialized AI agents (UX, backend, infra, frontend, FinOps) and a spec-driven process, so the way you build is standardized too — not only the stack.

💰 FinOps built in. Standardized cost-allocation tags on every AWS resource, AWS Budgets + Cost Anomaly Detection as code, and a finops agent that visualizes, optimizes, and operates cloud spend — 100% AWS-native, no third-party tools. Jump to FinOps (AWS-native).

---

Stack

Layer	Choice
Language	TypeScript (strict)
Framework	Next.js 16 (App Router) + React 19
UI	shadcn/ui (Base UI + Nova) · Tailwind CSS 4 · next-themes · sonner · lucide
Auth	NextAuth / Auth.js v5 (Google)
Payments	Stripe (Checkout + signature-verified webhooks)
Email	Resend
Database	Drizzle ORM + Postgres
Forms	react-hook-form + zod
i18n	next-intl (EN / JA, cookie-based — no URL restructure)
Observability	Sentry + PostHog (no-op without keys)
Testing / CI	Vitest + Testing Library · Playwright · GitHub Actions
Infra	AWS CDK → Amplify Hosting (SSR) + Secrets Manager
Secrets	AWS Secrets Manager, pulled per project — never committed
FinOps	AWS-native — cost-allocation tags, Budgets, Cost Anomaly Detection, Cost Optimization Hub + finops agent

---

Quick start

pnpm install

# Configure secrets — either pull from AWS Secrets Manager…
pnpm secrets:pull <secret-id>        # writes .env.local (git-ignored)
# …or copy the template and fill it in by hand:
cp .env.example .env.local

# Set up the database (any Postgres — RDS/Aurora, Neon, Supabase, local)
pnpm db:push

pnpm dev                             # http://localhost:3000

Generate AUTH_SECRET with openssl rand -base64 32. See SECRETS.md for the full secrets model and which keys are reusable across projects.

---

The AI team & spec-driven workflow

Open the repo in Claude Code. The .claude/ config gives you five specialist agents and a phased workflow.

Agents (each owns a lane and hands off a contract):

• ux-lead — flows, states, accessibility, design-system quality
• backend-dev — data model, OpenAPI contract, business logic, auth
• infra-architect — CDK stacks, AWS topology, security, cost
• frontend-dev — Next.js UI, shadcn, API integration
• finops — visualize/optimize/operate cloud cost (budgets, anomaly detection, tag governance)

Workflow — every feature is one specs/<NNN>-<slug>/SPEC.md with three sections (Requirements → Design → Tasks), each approved before the next:

/new-feature <slug>      # scaffold + fill §1 Requirements (ux-lead)
/design <NNN-slug>       # all agents fill §2 Design; freeze API + UX contracts
/tasks  <NNN-slug>       # break §2 into an ownership-tagged, parallel checklist
# …implement…
/spec-check <NNN-slug>   # audit code vs every acceptance criterion + contract drift

Quality reviews (on demand): /ux-review, /api-review, /infra-review. FinOps (cloud cost): /cost-report, /cost-optimize, /finops-setup.

The rule enforced throughout: no implementation before the spec is agreed, and any contract change goes back into the spec first. See CLAUDE.md and specs/001-infrastructure/SPEC.md for a worked example.

---

FinOps (AWS-native)

Cloud cost is a first-class concern, handled by a dedicated finops agent and built entirely on AWS-native services — no third-party cost tooling. It follows the FinOps Framework's three phases:

Phase	AWS-native tools	Command / code
Visualize	Cost Explorer, Cost & Usage Report / Data Exports, cost-allocation tags	pnpm cost:report · /cost-report
Optimize	Cost Optimization Hub, Compute Optimizer, Savings Plans & rightsizing recs, Trusted Advisor	pnpm cost:optimize · /cost-optimize
Operate	AWS Budgets, Cost Anomaly Detection, Cost Categories, Tag Policies	infra/lib/finops.ts · /finops-setup

• Every AWS resource is tagged with standardized cost-allocation tags (Project, Environment, Owner, CostCenter, Application, ManagedBy, Component).
• Budgets + anomaly detection are provisioned as code, scoped to the Project tag:

  cd infra && pnpm deploy -c alertEmail=finops@co.com -c monthlyBudget=200 \
                          -c owner=platform-team -c costCenter=CC-1001

• The agent is read-only by default — it recommends; changes ship as reviewable CDK.
• In-app cost dashboard at /dashboard/costs — spend by Project tag, rendered in the app's own UI from Cost Explorer.
• Tag governance — a CDK Aspect fails synth if a resource is missing required cost tags.
• Automation (opt-in) — budget auto-remediation (deny policy on breach), SNS→Slack alerts (pnpm cost:slack), and a FOCUS 1.0 data export to S3 for Athena/QuickSight.

Full setup (enabling Cost Explorer / Cost Optimization Hub / Compute Optimizer, activating tags, dashboard, exports) is in docs/FINOPS.md.

Project structure

.
├── .claude/              # AI team: agents, slash commands, settings, format hook
├── specs/                # spec-driven features (000 = template, 001 = infra)
├── src/
│   ├── app/              # routes, API handlers, error/loading/not-found, sitemap/robots
│   ├── components/       # ui/ (shadcn), providers, forms
│   ├── db/               # Drizzle schema + client
│   ├── i18n/             # next-intl config + locale
│   ├── lib/              # stripe, resend, secrets, utils
│   ├── auth.ts           # full NextAuth config (+ auth.config.ts edge-safe slice)
│   ├── env.ts            # type-safe, lazily-validated env
│   └── proxy.ts          # edge auth (protects /dashboard/*)
├── infra/                # AWS CDK — Amplify Hosting + Secrets Manager
├── messages/             # en.json / ja.json
└── CLAUDE.md, SECRETS.md

---

Commands

Command	Does
pnpm dev	Start dev server
pnpm build	Production build
pnpm test	Unit tests (Vitest)
pnpm test:e2e	End-to-end tests (Playwright)
pnpm lint / typecheck / format	Quality gates
pnpm db:push / db:generate / db:migrate / db:studio	Drizzle
pnpm secrets:pull <id>	Pull secrets from AWS → .env.local
pnpm cost:report / cost:optimize	FinOps — AWS-native cost + savings
cd infra && pnpm synth / diff / deploy	CDK infra

---

Deploy

Hosting is AWS Amplify (Next.js SSR), provisioned by CDK with env vars hydrated from Secrets Manager as CloudFormation dynamic references (no plaintext secrets in the template or git). See infra/README.md.

aws secretsmanager create-secret --name <app>/dev --secret-string '{ ...keys... }'
cd infra && pnpm cdk bootstrap        # once per account/region
pnpm diff                              # review — always
pnpm deploy -c appUrl=https://app.example.com -c repositoryUrl=https://github.com/org/repo

---

Docs

• docs/ARCHITECTURE.md — system diagram (renders on GitHub). Push it to a Miro board with pnpm miro:sync (docs/MIRO.md).
• docs/FINOPS.md — standardized AWS cost-allocation tags (Project, Environment, Owner, CostCenter, …) applied to every resource, and how to activate them in Billing.
• SECRETS.md · CLAUDE.md · infra/README.md

Security

• Secrets live in AWS Secrets Manager; only .env.example (placeholders) is committed. .env* is git-ignored.
• The synthesized CDK template contains zero plaintext secrets — values are dynamic references.
• IAM is least-privilege; security headers are set in next.config.ts.

Never commit a real key. If one leaks, rotate it immediately.

---

License

MIT — see LICENSE. Use it, fork it, build on it.