ドキュメント品質 PDCA ハーネス

既存記事をガイドラインに寄せるための Plan → Do → Check → Act 手順です。自動キックは Claude Code クラウド側で行い、このリポジトリに cron や schedule WF は置きません。実行手順の正本スキルは .claude/skills/doc-quality-pdca/SKILL.md です。

目的

ガイドライン逸脱を見つけ、小さな単位で直し、機械チェックを通し、人間レビューに渡す。一度に全記事を直さない。カテゴリまたは明示ファイル一覧を 1 バッチとする。

役割分担

フェーズ	担当	内容
Plan	`guideline-auditor` + `guideline-audit` スキル	逸脱の検索・一覧のみ。修正しない。Haiku 系
Do	`blog-writer` + `tech-note-writing` スキル	承認済み・優先付け済みの指摘だけ修正
Check	lint-prose / docs:build / verify-agent-docs	Layer 1。必要なら quality-gates の自己評価
Act	人間	PR レビュー・マージ。次回バッチの対象決定

リポジトリの PR に ai-review が付く場合は、Do 後の自己修正ループとして Check を補強できます。キック自体はクラウド側です。

バッチの切り方

未指定ならトップレベル単位にする。例: doc/blog/aws、doc/blog/datadog、doc/blog/newrelic、doc/blog/opentelemetry、doc/blog/prometheus、doc/blog/zabbix、ルート直下の個別 md。

1 バッチの修正は、機械検出（強調・AI フレーズ等）を優先し、件数が多いときは上位 N 件（指示がなければ 10 件程度）に抑える。公式整合の疑いは Plan では「疑い」止めとし、Do に進む前に人間または明示指示で対象を確定する。

一時成果物は temp/ のみ（例: temp/pdca-audit-<batch>.md）。作業後に削除する。コミットしない。

フェーズ詳細

Plan（監査）

AGENTS.md と doc/agent/blog-writing.md を読む
guideline-auditor（または guideline-audit スキル）で対象を監査する
出力はパス・観点・短い根拠・出典（lint / qualitative）の一覧と件数サマリ
修正・PR・push はしない

Do（修正）

Plan の一覧、または指示で渡されたファイルリストだけを対象にする
blog-writer / tech-note-writing に従い最小修正する
公式準拠の疑いは、指示で「修正してよい」と明示されたものだけ直す
結論セクション追加やスコープ外リライトはしない

Check（検証）

bash

npm run lint:prose -- <変更ファイル...>
npm run docs:build
# 指示書を触った場合のみ
node scripts/verify-agent-docs.js

Act（人手）

PR を出し、人間がレビューする。マージ後、残件があれば次バッチで Plan から再開する。

クラウドからの起動（指示の書き方）

Claude Code クラウドでは、モードを一文で指定し、対象バッチを必ず書く。ハーネスを活かすには「スキル名」か「PDCA」「監査のみ」「修正まで」を明示する。

監査のみ（Plan）

doc-quality-pdca の Plan だけ実行して。
対象: doc/blog/datadog
guideline-auditor（Haiku）で監査し、逸脱一覧だけ返して。修正・PR・push はしない。
必要なら結果を temp/ に書いて作業後削除して。

機械検出の修正まで（Plan → Do → Check、定性は触らない）

doc-quality-pdca を実行して。
対象: doc/blog/zabbix
Plan で lint-prose 由来の逸脱を集約し、Do では本文の **強調** と AI 特有フレーズなど機械検出分だけ直す。
定性（公式疑い・口語）は直さない。
Check で lint:prose と docs:build を通して。PR 作成は指示があるまでしない。

監査結果を渡して修正（Do → Check）

doc-quality-pdca の Do と Check だけ実行して。
対象ファイルは次のとおり（Plan 済み）:
- doc/blog/aws/compute/aws-ec2-overview.md （bold）
- ...
blog-writing.md と tech-note-writing に従い最小修正。docs:build まで通す。

フル PDCA（Act は人手）

doc-quality-pdca のフルサイクルを実行して。
対象: doc/blog/prometheus
1) Plan: guideline-auditor で一覧
2) Do: 機械検出の上位 10 件だけ修正
3) Check: lint:prose + docs:build
4) Act: ブランチを切って PR を作り、レビュー待ちにする。マージはしない。

避けたい指示

対象範囲なしの「全部直して」、監査なしの大規模リライト、公式疑いを断定して一括修正、結論セクションの追加、ハーネスを無視した場当たり修正。

成果物の目安

モード	期待する出力
Plan	逸脱一覧 + サマリ（リポジトリ変更なし）
Do + Check	最小 diff + lint/build 成功
フル	上記 + PR URL（マージなし）

ドキュメント品質 PDCA ハーネス ​

目的 ​

役割分担 ​

バッチの切り方 ​

フェーズ詳細 ​

Plan（監査） ​

Do（修正） ​

Check（検証） ​

Act（人手） ​

クラウドからの起動（指示の書き方） ​

監査のみ（Plan） ​

機械検出の修正まで（Plan → Do → Check、定性は触らない） ​

監査結果を渡して修正（Do → Check） ​

フル PDCA（Act は人手） ​

避けたい指示 ​

成果物の目安 ​

関連ファイル ​