dx-harness

DX Harness

リポジトリの開発者エクスペリエンスを支えるハーネスを監査、構築、保守します。ハーネスとは、開発ループを高速化するメタツール群です。ワンコマンドでのブートストラップ、リセット、シード、見つけやすい規約、エージェントに使いやすいエントリーポイントを備えています。

開発エクスペリエンスの劣化は現実に起こるため、このスキルが必要です。ハーネスは劣化し、手作業が再び増え、規約は徐々にずれていきます。そのコストは、毎日の小さな摩擦として積み重なります。このスキルは劣化を体系的に検出し、標準的な修正を適用します。

適用するタイミング

次の場合にこのスキルを使用します。

• ユーザーが繰り返し発生する手作業について説明する場合（「データベースをリセットするたびに再登録が必要」「作業を始める前にいつもこの3つのコマンドを実行している」など）
• ユーザーがオンボーディングに時間がかかると言及する場合、または「これをどうやって起動するのか」と尋ねる場合
• 新しいリポジトリをブートストラップする際に、最初からハーネスが必要な場合
• ユーザーが明示的にDX の監査または初回コミットまでの時間（TTFC）の測定を依頼する場合
• ユーザーが不足しているブートストラップ／リセット／シードスクリプトや AGENTS.md の修正を依頼する場合
• 定期的なメンテナンス作業が必要な場合（リリース後や、新しいエンジニアのオンボーディング後など）

ワークフローの概要

┌────────────────────────────────────────────────────────────┐
│  1. DISCOVER     scripts/discover.sh → repo-fingerprint    │
│  2. AUDIT        scripts/audit.sh    → dx-audit.json       │
│  3. PRIORITIZE   scripts/prioritize.sh → ranked findings   │
│  4. SCAFFOLD     scripts/scaffold-*.sh → scratch dir       │
│  5. CONFIRM      show diff to user; user picks what to apply│
│  6. VERIFY       scripts/verify.sh → assertions + timing   │
│  7. TRACK        scripts/track-attrition.sh → audit log    │
└────────────────────────────────────────────────────────────┘

構築した編集内容は、まずスクラッチディレクトリ（${TMPDIR}/dx-harness-<timestamp>/）に配置されます。ユーザーが差分を確認し、リポジトリにコピーする内容を選びます。作業ツリーへの予期しない書き込みはありません。

ツールの要件

必須：bash、git、node、jq。

実行時に検出されるツールチェーン（スキルは状況に応じて対応し、移行を強制することはありません）。

ツールチェーン	検出シグナル
npm/pnpm/yarn/bun	package.json、pnpm-lock.yaml、yarn.lock、bun.lockb
cargo	Cargo.toml
go modules	go.mod
Python (uv/poetry/pip)	pyproject.toml、uv.lock、poetry.lock、requirements.txt
just	Justfile または justfile
make	Makefile
docker compose	docker-compose.yml、compose.yaml
database (postgres)	docker-compose.yml の services、DATABASE_URL の環境変数参照

リスクレベル

書き込み。 このスキルはファイルを書き込みますが、ユーザーデータの削除、強制プッシュ、破壊的な操作は行いません。デフォルトでは、すべての内容をスクラッチディレクトリに配置します。適用する内容はユーザーが明示的に承認します。検証は別の git worktree で実行するため、所要時間の測定が作業ツリーに影響することはありません。

セットアップ

初回の呼び出し時に、スキルは config.json を確認し、必須フィールドが空の場合は AskUserQuestion を通じて入力を求めます。フィールドとデフォルト値については config.json を参照してください。

主なデフォルト値：

• ttfc_target_seconds: 60 — 初回コミットまでの目標時間（秒）
• apply_mode: "scratch" — 構築した編集内容をまずスクラッチディレクトリに配置し、ユーザーがコピーします
• audit_log_path: "${CLAUDE_PLUGIN_DATA}/dx-harness/audits.log" — 劣化の履歴を永続的に記録します

クイックリファレンス

監査と構築を一通り実行する

bash scripts/discover.sh > /tmp/fingerprint.json
bash scripts/audit.sh /tmp/fingerprint.json > /tmp/audit.json
bash scripts/prioritize.sh /tmp/audit.json

特定のハーネス要素を構築する

bash scripts/scaffold-bootstrap.sh   /tmp/fingerprint.json
bash scripts/scaffold-reset.sh       /tmp/fingerprint.json
bash scripts/scaffold-seed.sh        /tmp/fingerprint.json
bash scripts/scaffold-agents-md.sh   /tmp/fingerprint.json
bash scripts/scaffold-justfile.sh    /tmp/fingerprint.json

ハーネスがエンドツーエンドで機能することを検証する

bash scripts/verify.sh
# runs bootstrap in a scratch worktree, times it, asserts TTFC < target

経時的な劣化を追跡する

bash scripts/track-attrition.sh /tmp/audit.json
# appends to audits.log, prints diff vs previous run

使用方法

ワークフロースクリプトは各ステップの間で JSON を生成するため、組み合わせて実行できます。エージェントは、エラー処理や停止してユーザーに確認を求めるタイミングを含む、手順ごとの詳しいオーケストレーションについて、references/workflow.md を読む必要があります。

詳しい情報については、次を参照してください。

ファイル	読むタイミング
references/workflow.md	ワークフローを実行するとき（必ずここから始めます）
references/audit-checklist.md	audit.sh が何を、なぜ確認するのか理解するとき
references/fix-recipes.md	検出結果にどの構築スクリプトを適用するか選ぶとき
references/attrition-patterns.md	DX の劣化を示す兆候を git 履歴から読み取るとき

注意点

gotchas.md を参照してください。時間とともに判明した失敗の要因を蓄積しています。既存の内容を書き換えず、必ず新しい項目を追記してください。

関連スキル

• dev-skill:* — エージェントに使いやすい新しいスキルの作成に使用します（AGENTS.md のスキャフォールディング処理の出力でスキルが参照されることがよくあります）
• bug-review — 相性のよい組み合わせです。DX の悪さは、繰り返し発生するバグのカテゴリとして表面化することがよくあります