Skip to content
PETROVA

CLAUDE.md template

The template the bootstrap agent (core/prompts/00-bootstrap.md) copies into a consumer repo. <<PLACEHOLDER>> tokens are replaced from Phase-1 spec reading and Phase-2 calibration answers.

CLAUDE.md
> **Template note (delete this block on first commit).**
> This is the workspace projection. A fresh Claude Code session reads this
> file before anything else. It must answer four questions in order: *what
> is this for, how do I run it, how is it shaped, what conventions apply*.
> Anything else belongs in the linked docs, not here.
>
> **Shared methodology is included by reference.** Lines marked
> `<<INCLUDE: @shared/<file>.md>>` are expanded at bootstrap time from
> `core/templates/shared/`. Do not paste shared content inline — that
> re-introduces the duplication `shared/` exists to fix.
>
> Target length for the *project-specific* portion: 80–150 lines for a
> full-stack repo. The expanded shared sections add ≈80 lines on top.
> If your project-specific portion is longer, content is leaking that
> should be in `docs/`.


This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.


## What <<PROJECT_NAME>> is for


<<ONE_PARAGRAPH_PROBLEM_STATEMENT>>


<<NORTH_STAR_INTENT_SUMMARY>> — the full intent lives at
`docs/north-star/intent.md`. `docs/north-star/realignment-criteria.md`
defines the objective gate for <<REALIGNMENT_TRIGGER_DESCRIPTION>>.
For the methodology of how north-star works in every petrova-line repo,
see `docs/META-RULES.md` (`MR-1`) and the shared
`north-star-methodology.md` referenced below.


**Phase status (as of <<ISO_DATE>>).** <<CURRENT_PHASE_SUMMARY>>. See
`MILESTONES.md` for the full phase schedule. Phase discipline is shared
across all petrova-line repos — see the included `phase-discipline.md`
section below.


## Build, test, run


The `<<CANONICAL_BUILD_FILE>>` is canonical — `<<CANONICAL_TEST_COMMAND>>`
reproduces what CI runs.


```bash
# Backend
<<BACKEND_INSTALL_CMD>>
<<BACKEND_DEV_CMD>>
<<BACKEND_TEST_CMD>>


# Frontend
<<FRONTEND_INSTALL_CMD>>
<<FRONTEND_DEV_CMD>>
<<FRONTEND_TYPECHECK_CMD>>
<<FRONTEND_TEST_CMD>>


# Database
<<DB_MIGRATE_CMD>>
<<DB_SEED_CMD>>


# End-to-end
<<E2E_CMD>>


# The full matrix CI runs
<<FULL_CI_CMD>>

<<DEV_VS_PROD_SHAPE_NOTE>>

Architecture: <<KEY_ARCHITECTURAL_LENS>>

Section titled “Architecture: <<KEY_ARCHITECTURAL_LENS>>”

<<ARCHITECTURAL_PARAGRAPH>>

  • <<TIER_1_DIR>>/ — <<TIER_1_DESCRIPTION>>. <<TIER_1_KEY_INVARIANT_REF>>.
  • <<TIER_2_DIR>>/ — <<TIER_2_DESCRIPTION>>. <<TIER_2_KEY_INVARIANT_REF>>.
  • <<TIER_3_DIR>>/ — <<TIER_3_DESCRIPTION>>. <<TIER_3_KEY_INVARIANT_REF>>.
  • <<CONTRACTS_DIR>>/ — wire boundary. Schemas live at <<SCHEMA_PATH>>.

Cross-repo: <<EXTERNAL_DEPENDENCY_NAME>> (if applicable)

Section titled “Cross-repo: <<EXTERNAL_DEPENDENCY_NAME>> (if applicable)”

<<EXTERNAL_DEPENDENCY_DESCRIPTION>> at <<EXTERNAL_DEPENDENCY_PATH>>. <<HOW_THIS_REPO_TALKS_TO_IT>>. <<WHERE_CREDENTIALS_LIVE>>.

Diagnostic shortcut: if <<COMMON_FAILURE_MODE>>, see <<MEMORY_FILE_OR_RUNBOOK>>.

Documentation hierarchy

Section titled “Documentation hierarchy”

<<INCLUDE: @shared/documentation-hierarchy.md>>

Phase discipline

Section titled “Phase discipline”

<<INCLUDE: @shared/phase-discipline.md>>

Agent fleet

Section titled “Agent fleet”

<<INCLUDE: @shared/agent-fleet-methodology.md>>

The roster (who exists, what they read/write, how they hand off) lives in AGENTS.xml. Add roles there — never improvise (MR-6).

Invariants

Section titled “Invariants”

These are numbered and stable. Citations to them in code comments / decision docs use (I-N). Cross-cutting MR-N invariants live in docs/META-RULES.md.

  • I-1. <<INVARIANT_1>> (cited from <<SPEC_PATH_1>>).
  • I-2. <<INVARIANT_2>> (cited from <<SPEC_PATH_2>>).
  • I-3. <<INVARIANT_3>> (cited from <<SPEC_PATH_3>>).
  • (extend as needed; keep grounded in docs/spec/)

Drift watches

Section titled “Drift watches”

Anti-shapes this project drifts toward. When a PR or planning conversation feels off, ask: am I drifting toward $ANTISHAPE?

  • <<ANTISHAPE_1_NAME>> — <<ANTISHAPE_1_DESCRIPTION>>. Counter-anchor: <<ANTISHAPE_1_COUNTER>>.
  • <<ANTISHAPE_2_NAME>> — <<ANTISHAPE_2_DESCRIPTION>>. Counter-anchor: <<ANTISHAPE_2_COUNTER>>.

Universal conventions

Section titled “Universal conventions”

<<INCLUDE: @shared/conventions.md>>

Conventions specific to this repo

Section titled “Conventions specific to this repo”

These augment (never override) the universal conventions above. If a project convention conflicts with a shared one, open a decision doc recording the deviation and its trigger.

  • <<CONVENTION_1>>. <<JUSTIFICATION_OR_EXAMPLE>>.
  • <<CONVENTION_2>>. <<JUSTIFICATION_OR_EXAMPLE>>.
  • Direct push to main is OK for <<DIRECT_PUSH_BOUNDARY>> (refines the shared “small fixes” rule).

Where to look when stuck

Section titled “Where to look when stuck”

<<INCLUDE: @shared/navigation-index.md>>