A scaffolding framework for agentic data-analysis projects with Claude Code as the operator.
The framework's job is claim integrity: every quantitative assertion you make to a stakeholder is backed by a finding ID, a reproducing code path, declared filters, and a counterfactual tag. Validation runs as exit-code; hooks block bad commits; templates carry caveats forward.
This is scaffolding, not a runtime library. Once a project is created, it has no runtime dependency on analysis-kit — upgrades are deliberate, opt-in copies of the templates.
- 📖 USER_GUIDE.md — read this first. Plain-language tour with diagrams: how validation works, every template explained, common workflows, troubleshooting, when not to use.
- PHILOSOPHY.md — principles
- PROVENANCE_CONTRACT.md —
findings.jsonschema reference - COUNTERFACTUAL_TAGGING.md —
OBSERVED/PLAUSIBLE/WEAKrules - HOOKS_GUIDE.md — hook contracts and failure modes
# Clone analysis-kit somewhere
git clone <your-fork-url> ~/dev/analysis-kit
# Create a new analysis project
~/dev/analysis-kit/bootstrap/new-project.sh ./my-analysis --minimum
cd my-analysis
pip install -r requirements.txt
claude # opens Claude Code; reads CLAUDE.md → follows the disciplineInstall three workflow skills (/akit-start, /akit-fill, /akit-finding) plus an index (/akit) globally so Claude Code can guide users through the analysis-kit lifecycle:
~/dev/analysis-kit/bootstrap/install-skills.shThen in any new project: /akit-start <name> → drop reference materials → /akit-fill → /akit-finding "<hypothesis>" for each claim. See skills/ for the source markdown.
The repo ships a .devcontainer/ config so you can open it in VS Code with a reproducible environment in one click:
- Open the repo folder in VS Code.
- When prompted ("Reopen in Container"), accept — or run
Dev Containers: Reopen in Containerfrom the command palette. - Wait for the build (~2 min first time). Post-create runs
pytestas a smoke test.
You get Python 3.13, pinned pandas/pandera/numpy/pytest, Quarto, jq, and the gh CLI — all verified together. See .devcontainer/ for the exact pins.
Tiers:
--minimum— CLAUDE.md, six live-docs,validate.py,memory/,.claude/hooks/. Pandera in deps.--full— adds Quarto vignette pipeline,_quarto.yml, optional Datasette UI.
| Contract | File | Purpose |
|---|---|---|
| Trust gate | analysis/validate.py |
Exit 0 = trustworthy. Stop hook fires --fast; commit hook blocks on full. |
| Claims ledger | analysis/output/findings.json |
Every claim has F-NNN id, code_path, data_contract, caveats, counterfactual_tag, measurement_ref. |
| Live docs | live-docs/*.md |
TRUST_MEMO, DATA_PROFILE, DECISIONS, ANALYSIS_BACKLOG, TOOLING, METHODOLOGY_LOG — peers, all amendable. |
| Caveat carriers | memory/*.md |
Preconditions the agent reads before aggregating. Templates declare shape, projects fill content. |
| Hooks | .claude/hooks/ |
validate-on-stop (fast), block-unvalidated-commit (full), findings-coverage-on-edit (soft warn). |
- Not a pipeline runner. Use Kedro or Snakemake for orchestration.
- Not a notebook framework. Use Ploomber for notebook-first work.
- Not an MLflow replacement. Use MLflow for modelling.
- Not a BI tool. Use Evidence.dev for warehouse-resident BI.
It is dbt-tests-for-pandas-projects, with claims as the unit of trust, designed for an LLM operator.
In one sentence: constrain the agent's improvisational surface so deterministic guardrails can do the work. See docs/PHILOSOPHY.md for the full statement.
v0.2.0. The five contracts are stable; tier system, Pandera integration, and 35 self-tests pass. Validated end-to-end against a 35-finding production project (caught 3 stale findings the project's own validator hadn't flagged). Quarto integration shipped; Datasette deferred to v0.3.