# <PROJECT NAME>
#
# ─────────────────────────────────────────────────────────────────────────────
#  CLAUDE.md — golden template  ·  QRefAI AI Coding Field Guide, Part 2 (Q2.1)
#
#  BUDGET: keep this whole file LEAN — roughly 200–300 lines, ideally under 200.
#  Why: frontier models reliably follow ~150–200 instructions, and Claude Code's
#  own system prompt already spends ~50 of them. Every line here competes for that
#  budget. If a section grows past a few lines, it's probably a SKILL, not memory.
#
#  WHAT BELONGS HERE: only what is ALWAYS true and UNGUESSABLE.
#  WHAT DOES NOT:  anything your linter/formatter enforces (don't restate rules),
#                  and anything situational (push it into a skill).
#
#  Lines beginning with "#" are guidance for the author and can be deleted once
#  you've filled the file in. Replace every <PLACEHOLDER>.
# ─────────────────────────────────────────────────────────────────────────────

<ONE-PARAGRAPH PROJECT OVERVIEW. What this service does, in plain terms, and where
it sits in the wider platform. Two or three sentences. Example:
"Backend service handling card authorization and settlement. Part of the Acme
polyrepo platform — see @AGENTS.md for org-wide conventions.">

# The @import below makes THIS file a thin, Claude-specific layer over a shared,
# vendor-neutral AGENTS.md. Keep org-wide context in AGENTS.md; keep only
# Claude-specific overrides here. (As of mid-2026 Claude Code does not read
# AGENTS.md directly — the @import or a symlink is the bridge.)
Org-wide conventions: @AGENTS.md

## Stack
# Languages, frameworks, datastores, runtime targets — WITH VERSIONS.
# Versions matter: they're unguessable and they change agent behavior.
- <LANGUAGE + VERSION, e.g. Go 1.23>
- <DATASTORE + VERSION, e.g. PostgreSQL 16>
- <FRAMEWORK / TRANSPORT, e.g. gRPC>
- <DEPLOY TARGET, e.g. deployed to EKS>

## Commands
# The things Claude genuinely cannot guess. Use your real task runner.
# Annotate any command with a hard rule (e.g. "must pass before any commit").
- Build:   `<build command, e.g. make build>`
- Test:    `<test command, e.g. make test>`        # must pass before any commit
- Lint:    `<lint command, e.g. make lint>`         # CI-enforced; do NOT restate its rules here
- Run:     `<local run command>`
- Migrate: `<db migration command, e.g. make db-migrate>`

## Conventions Claude can't infer
# The high-value section. Each line is a rule the agent would NOT learn by reading
# the code, and that you'd otherwise have to repeat in every review. Keep to facts,
# not style the linter already covers. Examples (replace with your own):
- <e.g. All money is int64 minor units. Never use floats for currency.>
- <e.g. Every external call goes through `internal/clients/` — never inline an HTTP client.>
- <e.g. New endpoints require an entry in `docs/api-changelog.md`.>
- <e.g. Never write code that deletes from an audit/ledger table.>

## Where things live
# A SHORT orientation map — module → purpose. Keep it high-level; the agent can
# discover file-level detail itself. Omit this entirely if your layout follows a
# framework convention the agent already knows.
- <e.g. Business logic:        `internal/domain/`>
- <e.g. HTTP/gRPC handlers:    `internal/transport/`>
- <e.g. DB access:             `internal/store/`>

# ─────────────────────────────────────────────────────────────────────────────
#  ROUTING REMINDER (delete before shipping):
#  • Always-true fact about THIS project        → it belongs here.
#  • "How we do X" task playbook                → make it a SKILL, not a section.
#  • A 100-line checklist / code template       → skill reference file.
#  • A worker with a role (reviewer, etc.)      → a SUBAGENT.
#  If you just pasted a long checklist above, stop — that's a skill waiting to be
#  written. Keep this file short enough that the agent actually follows all of it.
# ─────────────────────────────────────────────────────────────────────────────