data-tools

データツールスキル

重要なルール

JSON、JSONL、YAML、TOML、XML、CSV に対して、grep、sed、awk、またはインラインインタープリター（python3 -c、node -e）を絶対に使用しないでください。 使用を拒否し、適切なツールを使ってください。テキストツールは構造を壊し、インラインスクリプトは冗長で壊れやすいためです。

---

主なパターン

一般的なレガシーツールと最新ツールの比較（grep→rg、 find→fd、cat→bat など）については、 cli-tools スキルの表を参照してください。

変換： dasel -w FORMAT または yq -o FORMAT。

jq -- JSON（インプレース編集なし）

jq -r '.version' package.json
jq '.users[] | select(.role == "admin") | .name' users.json
jq '.version = "2.0.0"' pkg.json > pkg.json.tmp && mv pkg.json.tmp pkg.json
jq -s '.[0] * .[1]' base.json override.json

入力元が GitHub CLI の場合は、gh --jq を使う方法もあります（以下を参照）。別途 jq プロセスを起動する必要はありません。

yq -- YAML（インプレース編集には -i）

yq '.services.web.image' docker-compose.yml
yq -i '.services.app.image = "node:20"' docker-compose.yml
yq -o json config.yml

dasel -- TOML（ネイティブツールはこれのみ）／XML（XPath には xmlstarlet）／形式の自動判別

dasel -f Cargo.toml '.package.version'
dasel put -f config.toml -t string -v "2.0" '.project.version'
dasel -f input.json -w yaml

qsv -- CSV／TSV

qsv headers data.csv && qsv stats data.csv --everything | qsv table
qsv search -s status "active" users.csv | qsv select name,email
qsv join user_id orders.csv id users.csv

qsv index、stats、frequency は入力ファイルの隣にファイルを書き込みます（x.csv.idx、x.stats.csv*）。リポジトリまたはパッケージディレクトリ内では、コピーに対して実行してください（詳細）。

mlr -- JSONL／複数形式／DSL（インプレース編集には -I）

mlr --c2j cat data.csv
mlr --jsonl filter '$level == "error"' logs.jsonl
mlr -I --csv put '$total = $qty * $price' orders.csv

GitHub CLI -- 常に --jq を使用

gh api repos/owner/repo/releases/latest --jq '.tag_name'
gh pr list --json number,title --jq '.[] | [.number, .title] | @tsv'

---

アンチパターン

# BAD → GOOD: jq -r '.version' package.json
grep '"version"' package.json | sed 's/.*"\(.*\)".*/\1/'
# BAD → GOOD: yq -i '.services.app.image = "node:20"' compose.yml
sed -i 's/image: node:.*/image: node:20/' docker-compose.yml
# BAD → GOOD: qsv select 2 data.csv
awk -F',' '{print $2}' data.csv
# BAD → GOOD: jq -r '.version' plugin.json
python3 -c 'import json;print(json.load(open("plugin.json"))["version"])'

---

参考資料

レシピ集	内容
jq レシピ集	フィルタリング、変換、GitHub CLI、大容量入力（「Argument list too long」、Windows）
yq レシピ集	Actions、Compose、K8s
dasel レシピ集	TOML／XML、変換
CSV 処理	qsv ワークフロー、結合
mlr レシピ集	JSONL、DSL、統計、結合
強制適用フック	このプラグインに付属する PreToolUse ゲート：フィールド抽出を拒否し、それ以外の場合は一度だけ警告

ドキュメント：jq、yq、dasel、qsv、mlr。