CLAUDE.md スターター

すべてのレベル

CLAUDE.md は、Claude Code に与えられる最も効果の高いものです。これはセッションのたびに読み込まれる永続的な指示です。これらのいずれかをリポジトリのルートに置き（あるいは /init を実行して出発点を生成し）、自分に合うように削ぎ落としてください。各ブロックのコピーボタンを使ってください。

:::tip 短く、そして真実に 長く、理想論的で、最新でない CLAUDE.md は害になります — Claude はそれを文字どおりに従います。プロジェクトが実際にどう動いているかを記述し、容赦なく刈り込んでください。詳しくは CLAUDE.md のページを参照してください。 :::

汎用スターター

# Project: <name>


## What this is

<One or two sentences: what the project does and who uses it.>


## Tech stack

- Language/runtime: <e.g. TypeScript, Node 20>
- Framework: <e.g. Next.js 14 App Router>
- Key libraries: <e.g. Prisma, tRPC, Tailwind>


## How to run

- Install: `<cmd>`
- Dev server: `<cmd>`
- Tests: `<cmd>`
- Lint/format: `<cmd>`


## Conventions

- <e.g. Use functional components; no class components.>
- <e.g. Co-locate tests as *.test.ts next to source.>
- <e.g. Conventional Commits for messages.>


## Guardrails

- Run the tests before saying a task is done.
- Don't edit files under `/generated` or `/vendor`.
- Never commit secrets or .env files.


## Good to know

- <Gotchas, non-obvious decisions, links to deeper docs.>

Node / TypeScript Web アプリ

# Project: <name> (Next.js + TypeScript)


## How to run

- Dev: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint` (must pass before commit)


## Conventions

- TypeScript strict; no `any` without a comment justifying it.
- Components in `src/components`, one folder per component.
- Data fetching via tRPC; never call the DB from a client component.
- Styling: Tailwind utility classes; no inline styles.


## Guardrails

- After any change, run `npm run lint && npm test`.
- Keep files under ~300 lines; split when larger.
- Do not modify `prisma/migrations` by hand.

Python サービス

# Project: <name> (FastAPI)


## How to run

- Install: `uv sync` (or `pip install -e .`)
- Dev: `uvicorn app.main:app --reload`
- Test: `pytest`
- Lint/format: `ruff check . && ruff format .`


## Conventions

- Type hints everywhere; prefer `pathlib` over `os.path`.
- Pydantic models for all request/response bodies.
- f-strings, not %-formatting.


## Guardrails

- Run `pytest` and `ruff check` before completing a task.
- Fail fast with descriptive errors; no silent excepts.

Django

# Project: <name> (Django <version>)

## Tech stack

- Python 3.12 · Django 5.x
- Database: PostgreSQL (psycopg3)           # or SQLite for local dev; state the truth
- Task queue: Celery + Redis               # remove if unused
- Auth: django-allauth / dj-rest-auth      # remove if unused
- API layer: Django REST Framework (DRF)   # remove if unused; note if it's pure server-side templates instead
- Frontend: HTMX + Alpine.js / React SPA   # pick one; state the truth
- Key packages: django-environ, Pillow, whitenoise


## Settings layout

# config/
#   settings/
#     base.py      ← shared
#     local.py     ← DEBUG=True, console email backend
#     production.py← env-driven secrets, ALLOWED_HOSTS, SECURE_* flags
# Load via DJANGO_SETTINGS_MODULE env var.


## How to run

- Install:      `pip install -e ".[dev]"` or `uv sync`
- Env file:     copy `.env.example` → `.env` and fill secrets
- Migrate:      `python manage.py migrate`
- Dev server:   `python manage.py runserver`
- Shell:        `python manage.py shell_plus`   # django-extensions
- Test:         `pytest` (pytest-django; see pytest.ini)
- Lint/format:  `ruff check . && ruff format .`
- Type check:   `mypy .`   # if mypy is configured


## Project layout

<project_slug>/
  <app_name>/
    models.py         # one model family per app; no god-models
    views.py          # CBVs preferred; FBVs for simple one-offs
    serializers.py    # DRF only
    urls.py           # app-level URL conf; included from config/urls.py
    services.py       # business logic lives here, NOT in views or models
    tasks.py          # Celery tasks
    tests/
      test_models.py
      test_views.py
  config/
    settings/
    urls.py
    wsgi.py / asgi.py
  manage.py


## Conventions

### Models
- Fat service layer, thin models: domain logic goes in `services.py`, not model methods.
- Always set `verbose_name` and `verbose_name_plural` on Meta.
- Use `get_object_or_404` or `select_related`/`prefetch_related` — never N+1 queries.
- UUID primary keys for all user-facing models: `id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)`.

### Migrations
- One migration per logical change; never squash without team sign-off.
- Never edit a migration that has been applied to staging or production.
- Name meaningful ones: `python manage.py makemigrations --name add_published_at_to_post`.

### Views & URLs
- Class-Based Views for CRUD and list/detail; Function-Based Views for anything with unusual branching.
- DRF ViewSets for API endpoints; routers in `<app>/urls.py`.
- All URLs namespaced: `app_name = "blog"` in each app's `urls.py`.

### Templates (if server-side rendered)
- Extend `base.html`; block names: `title`, `content`, `extra_css`, `extra_js`.
- No business logic in templates; use template tags or pass computed context from the view.

### Security
- `SECRET_KEY` and all credentials via environment variables (django-environ); never hardcoded.
- CSRF on all mutating endpoints; DRF uses `SessionAuthentication` + CSRF by default.
- `SECURE_SSL_REDIRECT`, `SESSION_COOKIE_SECURE`, `CSRF_COOKIE_SECURE` = True in production.


## Guardrails

- Run `pytest && ruff check .` before marking any task done.
- Never edit applied migrations; create a new one instead.
- Do not add raw SQL unless there is no ORM equivalent — document why if you do.
- Do not import from `django.conf.settings` inside model files; pass values explicitly.
- After adding a new dependency, update `pyproject.toml` (or `requirements/*.txt`) and note it here.


## Good to know

- `DEBUG=True` in local; `DEBUG=False` in all server environments — never skip this.
- Static files are served by WhiteNoise in production; run `collectstatic` before deploy.
- Celery worker: `celery -A config worker -l info`; beat: `celery -A config beat -l info`.
- <Add any project-specific gotchas: custom user model, multi-tenancy, third-party integrations.>

Go

# Project: <name> (Go <version>)


## What this is

<One or two sentences: what the service does and who uses it.>


## Tech stack

- Go 1.23+
- HTTP: net/http stdlib / chi / gin        # pick one; delete the rest
- Database: pgx + sqlc                     # or database/sql + sqlx; state what's true
- Migrations: golang-migrate               # remove if unused
- Config: envconfig / godotenv             # remove if unused
- Key deps: zap (logging), testify (assertions)


## How to run

- Install deps:  `go mod download`
- Build:         `go build ./...`
- Dev (live):    `air` (github.com/air-verse/air)   # remove if unused
- Test:          `go test ./... -race`
- Lint:          `golangci-lint run`
- Generate:      `go generate ./...`   # sqlc, mockgen, etc.


## Project layout

    cmd/
      <service>/
        main.go       # wiring only — no business logic
    internal/
      <domain>/
        service.go    # business logic
        repository.go # DB layer (interface + impl)
        handler.go    # HTTP handlers
    pkg/              # code safe to import from outside this module
    migrations/       # SQL migration files


## Conventions

- Package names: short, lowercase, no underscores (`userstore` not `user_store`).
- One package per domain concern inside `internal/`; avoid a god `utils` package.
- Errors: always wrap with `fmt.Errorf("doing X: %w", err)`; never discard.
- Interfaces: define them in the *consumer* package, not the producer.
- No global state; inject dependencies via constructor functions.
- context.Context is the first parameter of every function that does I/O.
- Prefer table-driven tests; subtests via `t.Run`.


## Guardrails

- Run `go test ./... -race && golangci-lint run` before marking any task done.
- Never use `panic` in library code; return errors.
- Do not use `init()` functions — wire everything in `main`.
- Avoid naked `interface{}`; use typed interfaces or generics (Go 1.18+).
- Keep `main.go` thin: parse config, build deps, call `server.Run`.


## Good to know

- `go generate` must be run after changing any `.sql` query files (sqlc).
- Linter config lives in `.golangci.yml` — do not add lint exceptions without a comment.
- <Add project-specific gotchas: service mesh, internal auth, proto generation.>

Rust

# Project: <name> (Rust <edition>)


## What this is

<One or two sentences: what this binary/library does and who uses it.>


## Tech stack

- Rust edition 2021, MSRV <version>
- Async runtime: Tokio                     # or async-std; pick one
- HTTP: Axum / Actix-web                   # remove unused
- Serialisation: serde + serde_json
- Database: sqlx (async, compile-time checked queries)   # remove if unused
- Error handling: thiserror (library) / anyhow (binary)  # pick per crate type
- Key crates: tracing, tracing-subscriber, dotenvy


## How to run

- Build (dev):   `cargo build`
- Build (rel):   `cargo build --release`
- Test:          `cargo test`
- Lint:          `cargo clippy -- -D warnings`
- Format:        `cargo fmt --check`
- Docs:          `cargo doc --open`
- Watch:         `cargo watch -x test`   # remove if unused


## Workspace layout (if multi-crate)

    Cargo.toml           # [workspace] root
    crates/
      core/              # domain logic, no I/O, no async
      api/               # Axum HTTP layer
      db/                # sqlx repository layer
      cli/               # binary entry-point


## Conventions

- No `unwrap()` or `expect()` in library crates; propagate with `?`.
- `expect()` in binaries only where a panic is truly unrecoverable — with a message explaining why.
- Prefer `thiserror` for library error enums; `anyhow` for binary/main error chains.
- Async only at the edges (HTTP handlers, DB calls); keep domain logic sync.
- Derive `Debug`, `Clone`, `serde::Serialize/Deserialize` where it makes sense.
- Feature flags in `Cargo.toml` for optional integrations; document each one.


## Guardrails

- Run `cargo test && cargo clippy -- -D warnings && cargo fmt --check` before done.
- Never silence a Clippy lint without a `#[allow(...)]` comment explaining why.
- Do not use `unsafe` without a `// SAFETY:` comment justifying it.
- Do not add a crate that duplicates one already in the dependency tree without discussion.
- Keep compile times in mind: prefer concrete types over heavy generics in hot paths.


## Good to know

- `sqlx` queries are checked at compile time — run `cargo sqlx prepare` to update the offline cache after changing queries.
- MSRV is enforced in CI; do not use features newer than the stated MSRV.
- <Add project-specific gotchas: WASM target, FFI boundaries, no_std constraints.>

どれにも当てはまるヒント

• 階層化する。 プロジェクト全体には、リポジトリのルートに CLAUDE.md を置きます。領域固有のルールには、サブフォルダにネストした CLAUDE.md ファイルを置きます。
• @imports を使うことで、既存のドキュメントを複製せずに取り込めます（CLAUDE.md リファレンスを参照）。
• 毎月見直す。 古くなった指示は、何もないよりも悪いものです。

関連

• 詳しい手順 → CLAUDE.md & Memory Files
• さらなるスターター → SKILL.md Templates、hooks & settings recipes
• これらの改善 → Contribute