From 28cc87c988e07caa5ab591d8f33f44e5e005f51d Mon Sep 17 00:00:00 2001 From: Diego Nieto Date: Wed, 26 Aug 2026 13:20:52 +0200 Subject: [PATCH 1/2] docs: require a short spec before TDD Add a lightweight spec step (problem + acceptance criteria) ahead of TDD in CLAUDE.md and AGENTS.md, written in the starting commit. Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 13 +++++++------ CLAUDE.md | 13 ++++++++----- 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ea94093..d089cb3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,12 +17,13 @@ quickly, then defer to `CLAUDE.md` for complete repository guidance. objects only after collection, dry-run review, explicit confirmation, and the applicable ClickHouse cluster/replica preflight. Do not weaken these controls without explicit approval and matching tests and documentation. -3. **Test coverage and required checks are mandatory.** For every feature, - bug fix, or material behaviour change, add a focused test when no existing - test covers it; use test-driven development for behaviour changes. Run the - relevant offline pytest suite and Kubernetes renderer/manifest dry-run - checks described in `CLAUDE.md`. Automated tests must not contact live - ClickHouse or object storage, or delete objects. +3. **Spec-first TDD and required checks are mandatory.** For every feature, + bug fix, or material behaviour change, start with a short spec (problem + + acceptance criteria) in the starting commit, then use test-driven + development to satisfy each criterion. Run the relevant offline pytest + suite and Kubernetes renderer/manifest dry-run checks described in + `CLAUDE.md`. Automated tests must not contact live ClickHouse or object + storage, or delete objects. 4. **No secrets or customer data in Git.** Never commit credentials, customer configuration, target-cluster details, or rendered customer manifests. Use Kubernetes Secrets or workload identity for production credentials. diff --git a/CLAUDE.md b/CLAUDE.md index 6f7e953..76d418c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,11 +14,14 @@ tests, explicit delete controls, and conservative deployment defaults. not retry automatically. A behavior change in this path needs regression tests and matching README/deployment documentation. -2. **Test coverage and TDD are mandatory.** For every new feature, bug fix, or - material operational behaviour change, identify the test that covers it; if - none exists, add a focused test in the same change. Start behaviour changes - with a failing test, and add a regression test for every defect. Purely - editorial changes are exempt. +2. **Spec-first TDD is mandatory.** For every new feature, bug fix, or + material operational behaviour change, start with a short spec in the + commit that begins the change: one or two sentences on the problem or + intent, plus a short bullet list of acceptance criteria — what must be true + when it's done. Then use TDD: for each acceptance criterion, write the + failing test that covers it before making it pass. Add a regression test + for every defect. Purely editorial changes are exempt from both the spec + and TDD. 3. **Tests stay offline by default.** Install both requirements files, then run `pytest -v` for relevant changes. Tests must use fakes, local From 4f408c4a9176cae919b614436dc3e80c6105f016 Mon Sep 17 00:00:00 2001 From: Diego Nieto Date: Wed, 26 Aug 2026 15:54:48 +0200 Subject: [PATCH 2/2] docs: add Spec Intake and document the workflow in README Spec Intake gives a short question list for under-specified requests. README now explains the spec-first TDD workflow for dev agents. Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 3 ++- CLAUDE.md | 23 +++++++++++++++++++---- README.md | 17 +++++++++++++++++ 3 files changed, 38 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d089cb3..f834b3c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,7 +19,8 @@ quickly, then defer to `CLAUDE.md` for complete repository guidance. controls without explicit approval and matching tests and documentation. 3. **Spec-first TDD and required checks are mandatory.** For every feature, bug fix, or material behaviour change, start with a short spec (problem + - acceptance criteria) in the starting commit, then use test-driven + acceptance criteria) in the starting commit. If the request doesn't already + answer that, run Spec Intake first (see `CLAUDE.md`). Then use test-driven development to satisfy each criterion. Run the relevant offline pytest suite and Kubernetes renderer/manifest dry-run checks described in `CLAUDE.md`. Automated tests must not contact live ClickHouse or object diff --git a/CLAUDE.md b/CLAUDE.md index 76d418c..090591c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,10 +18,11 @@ tests, explicit delete controls, and conservative deployment defaults. material operational behaviour change, start with a short spec in the commit that begins the change: one or two sentences on the problem or intent, plus a short bullet list of acceptance criteria — what must be true - when it's done. Then use TDD: for each acceptance criterion, write the - failing test that covers it before making it pass. Add a regression test - for every defect. Purely editorial changes are exempt from both the spec - and TDD. + when it's done. If the request doesn't already answer these, run Spec + Intake first (see below). Then use TDD: for each acceptance criterion, + write the failing test that covers it before making it pass. Add a + regression test for every defect. Purely editorial changes are exempt from + both the spec and TDD. 3. **Tests stay offline by default.** Install both requirements files, then run `pytest -v` for relevant changes. Tests must use fakes, local @@ -53,6 +54,20 @@ tests, explicit delete controls, and conservative deployment defaults. for possible, interesting, and deliberately deferred improvements. Do not treat a TODO item as already implemented or use the changelog as a backlog. +## Spec Intake + +When someone reports a bug or asks for a feature without enough detail to +write a spec, ask: + +1. What's happening, and what should happen instead? +2. How do you trigger it (steps or command)? +3. Does this touch the delete lifecycle (collect → dry-run → delete → verify) + or a safety check? +4. Any known edge cases, or things this must not break? + +Use the answers to write the spec's acceptance criteria. If the report +already answers these, skip straight to the spec. + ## Repository map | Path | Purpose | diff --git a/README.md b/README.md index 960d736..530b9c5 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,23 @@ For Claude Code, substitute `~/.claude/skills`. Invoke it with The skill does not permit an agent to supply the deletion confirmation; an authorized human must approve the reviewed dry-run result. +## AI coding workflow + +This repo uses `CLAUDE.md` (full guide) and `AGENTS.md` (short pointer) to +tell AI coding agents how to work here. If you ask an agent to fix a bug or +add a feature, here's what it does: + +1. **Spec Intake** — if you didn't give enough detail, the agent asks a few + short questions: what's happening vs. what should happen, how to trigger + it, whether it touches the delete lifecycle, and any known edge cases. +2. **Spec** — the agent writes a short spec (problem + acceptance criteria) + in the commit that starts the change. +3. **TDD** — for each acceptance criterion, the agent writes a failing test, + then makes it pass. + +This applies to new features, bug fixes, and behaviour changes. Editorial +changes (docs, comments) skip it. See `CLAUDE.md` for the full rules. + ## Direct script examples The following is a non-secret target configuration. Replace every