dx-harness

DX Harness

审计、搭建并维护仓库的开发者体验（DX）工具体系。工具体系是让开发循环快速运转的元工具：一条命令完成引导、一条命令重置、一条命令填充种子数据、约定清晰易查、入口便于 Agent 使用。

这项技能的存在，是因为开发体验退化确实存在：工具体系会逐渐失修，手动步骤又会增加，约定会偏离，而代价每天都体现在细微的摩擦中。这项技能会系统地检测退化并应用标准修复方案。

适用场景

在以下情况下触发此技能：

• 用户描述了反复出现的手动杂务（“每次重置数据库后，我都得重新注册”，“开始工作前，我总要先运行这三条命令”）
• 用户提到入门过程缓慢，或询问“如何让这个项目运行起来”
• 新仓库正在进行引导搭建，需要从一开始就配备工具体系
• 用户明确要求审计 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 中的服务、DATABASE_URL 环境变量引用

风险级别

写入。 此技能会写入文件，但不会删除用户数据、强制推送或运行破坏性操作。默认模式会将所有内容暂存到临时目录；每项修改都须经用户明确批准后才会应用。验证会在独立的 git 工作树中运行，因此计时测量不会触及工作区。

设置

首次调用时，此技能会检查 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，以便组合使用。Agent 应阅读 references/workflow.md，了解完整的分步编排，包括错误处理，以及何时停止并询问用户。

更多背景信息：

文件	何时阅读
references/workflow.md	执行工作流时（始终从这里开始）
references/audit-checklist.md	了解 audit.sh 检查的内容及原因
references/fix-recipes.md	根据检查结果选择适用的搭建脚本
references/attrition-patterns.md	从 git 历史中查找 DX 退化迹象

注意事项

请参阅 gotchas.md——这里汇总了随时间发现的问题点。发现新问题时，始终追加记录，不要重写已有内容。

相关技能

• dev-skill:* — 用于创建适合 Agent 使用的新技能（AGENTS.md 脚手架流程的输出通常会引用技能）
• bug-review — 与之搭配使用很合适：糟糕的开发者体验（DX）往往会反复暴露同类 Bug