Building with Claude

• Instead of writing a spec from scratch, let Claude question you until the gaps are gone.
• Save the spec in the repo. It becomes the brief for implementation and an example for the next feature.
• Break the plan into thin vertical slices, each one testable and shippable on its own.

I want to add [feature]. Before writing anything,
interview me. Ask one question at a time about:
users, edge cases, failure modes, tenant
boundaries and what's out of scope.

When you have enough, write a spec with:
goal, non-goals, API shape, data changes,
tests, and open questions.

Then split it into small slices, each one
shippable and testable on its own.

• Claude reads it at the start of every session, so everyone's Claude follows the same rules.
• Keep it short and specific to the project: commands, rules, definition of done.
• Every time you repeat an instruction, add it here instead.
• Commit it, and review changes to it like code.

# CLAUDE.md
## Commands
Tests: pytest -q        UI: pnpm test

## Non-negotiable
- Every query is tenant-scoped. No cross-tenant paths.
- Read a file before referencing anything in it.
- Smallest change that solves the task.
  Don't touch unrelated code. Flag it instead.
- Tests in the same change. Never edit a test to pass.
- Ask before adding a dependency.
- No magic numbers. Named constants or config.
- Never swallow exceptions. Fail loudly and early.
- Safe to run twice. Log state changes and calls.

## Definition of done
- Tests run locally. Paste the output.
- Docs updated if behaviour changed.
- List every file changed and why.

• For a bug, ask for a failing test first, then the fix.
• Every bug fix leaves a regression test behind.
• Never change a test to make it pass. Claude asks before modifying existing tests.
• Check the tests test behaviour, not that a mock returns what the mock was told to.
• Claude shows the test output. "Tests pass" without output doesn't count.

def test_reorder_qty_is_never_negative():
    assert reorder_qty(on_hand=50, target=30) == 0


def test_on_hand_is_tenant_scoped(repo):
    repo.seed(tenant_id="t1", style_id="S1", on_hand=5)
    repo.seed(tenant_id="t2", style_id="S1", on_hand=500)

    assert get_on_hand(
        repo, tenant_id="t1", style_id="S1"
    ) == 5

• Business logic takes values and returns values. Easy to test, no mocks.
• Thresholds come from config, not literals.
• Writes use upserts or keys, so a retry doesn't double-apply.
• State changes and external calls are logged with tenant context.

# Pure: no I/O, no hidden state
def compute_replenishment(stock, policy) -> int:
    target = policy.target_cover_days * stock.daily_rate
    return max(target - stock.on_hand, 0)


# Edge: reads, logs, writes
def run_replenishment(tenant_id, style_id) -> None:
    stock = stock_repo.get(tenant_id, style_id)
    policy = policy_repo.get(tenant_id)
    qty = compute_replenishment(stock, policy)
    logger.info("replenishment computed", extra={
        "tenant_id": tenant_id, "qty": qty,
    })
    order_repo.upsert(tenant_id, style_id, qty)

• Automation lives in the same repos, under the same review rules as production code.
• Synthetic data only. Fixtures come from factories, never from client exports.
• Every feature gets a tenant isolation test as standard.
• Every bug report comes with a failing test that reproduces it.
• An AI first-look review on each PR catches the basics: committed secrets, missing tests, unlinked tickets.

From this spec, write test cases for
allocation caps:
- happy path
- boundaries: 0, max, max + 1
- invalid and missing input
- one test proving tenant A cannot
  read or change tenant B's data

Use only synthetic data from
tests/factories.py.
Run the suite and show me the output.

• No blame. An AI-introduced bug passed through a prompt, a review and our tests. Fix the step that let it through.
• Give feedback on mistakes privately. Share the lesson publicly.
• Each encoded rule means one less thing a human has to catch.