# AI4S Task Harness Skill
**[中文版本 / Chinese Version](README_zh.md)**
A Claude Code skill framework for building **task-specific harnesses** in AI for Science (AI4S) projects — bioinformatics pipelines, model training, benchmarking, and data integration.
Inspired by Anthropic's [A Harness for Every Task: Dynamic Workflows in Claude Code](https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code), adapted for the AI4S research lifecycle where results go into manuscripts and reproducibility is non-negotiable.
## The Problem
AI4S projects fail in predictable ways:
| Failure | What happens |
|---|---|
| **Metric drift** | Paper says 92%, code now produces 89% |
| **Story drift** | Manuscript claims X, analysis code does Y |
| **Silent fallback** | Method A fails, code silently switches to B |
| **Artifact survival** | Shuffled labels still show "signal" |
| **Irreproducibility** | Results differ on re-run |
When using Claude Code for AI4S tasks, three additional failure modes from long agentic sessions compound the problem:
- **Agentic laziness** — Claude stops after step 2 of a 5-step pipeline
- **Self-preferential bias** — Claude judges its own output as "good enough"
- **Goal drift** — original scientific question gets lost over multiple iterations
## The Solution
Build a **harness** before writing analysis code. The harness is scaffolding that constrains Claude to work within data contracts, sanity checks, and evidence locks:
```
STORY_LOCK.md → narrative anchor (which sub-question?)
HYPOTHESIS.md → falsifiable claim (pre-registered)
harness/contracts/ → input schema assertions
harness/sanity/ → negative controls (shuffled labels, etc.)
harness/benchmarks/ → metric capture
harness/registry.py → phase registration
tests/test_contracts/→ locked headline numbers
Workflow scripts → parallel execution + adversarial verification
```
## What's Included
### `skill/` — The Claude Code Skill
- **`SKILL.md`** — 7-step harness build process, 4 AI4S workflow patterns, failure mode table, completeness checklist
- **`workflow-templates.js`** — Ready-to-adapt Claude Code dynamic workflow scripts:
- **Fan-Out Benchmark** — run pipeline across N datasets in parallel
- **Adversarial Verification** — independent agents try to break your analysis
- **Hypothesis Tournament** — competing explanations judged against evidence
- **Pipeline-Then-Audit** — sequential pipeline with per-step biological audit
### `command/` — The `/init_ai4s` Command
Scaffolds a new AI4S project from a natural-language spec. Generates lean, project-specific `AGENTS.md` — no boilerplate.
### `template/` — The Project Template
Folder skeleton, harness infrastructure, pre-commit hooks, and contract/sanity templates.
## Installation
```bash
# Skill
cp -r skill/ ~/.claude/skills/ai4s-task-harness/
# Command
cp command/init_ai4s.md ~/.claude/commands/
# Template
cp -r template/ ~/.claude/templates/ai4s-project/
```
## Usage
```bash
# Scaffold a new project
/init_ai4s 基于人类肝癌 scRNA-seq 数据研究肿瘤微环境中 TAM 亚群与 T cell exhaustion 的因果关系。数据在 ~/data/hcc/GSE149614，Tumor vs Adjacent，n=10
# Before each analysis task
/ai4s-task-harness
```
## Design Principles
**Lean AGENTS.md.** Global rules (coding style, reproducibility, security, bioinformatics standards) belong in `~/.claude/rules/`, not in per-project files. AGENTS.md should contain only project-specific constraints. Target: <80 lines.
**Harness before code.** Write the data contract and negative control before the analysis code. The contract defines what "correct input" means; the negative control defines what "no signal" looks like.
**Evidence is generated, not hand-written.** `harness/evidence_table.py` reads from `results/` and generates `plan/UNIFIED_EVIDENCE_TABLE.md`. Pre-commit hooks forbid manual edits. This is what stops manuscript-code drift.
**Workflows for scale, not ceremony.** Simple single-dataset analysis doesn't need a workflow script. Reserve dynamic workflows for genuine parallelism (multi-dataset benchmarks) or adversarial verification (main-text claims).
## Requirements
- [Claude Code](https://claude.com/claude-code) with skills support
- Python 3.10+
- `uv` (recommended) or `pip`
## License
MIT