docs-impl-consistency-audit

name	docs_impl_consistency_audit
description	LP(website/) と人間向けドキュメント(docs/・README) と実装(crates/) が「同じ一つの事実」を語っているかを横断監査する。用語・アーキテクチャ・CLI 表面・機能主張・ja/en 整合・禁止表現を点検し、不整合を file:line と修正案つきで報告する。リリース前やドキュメント/LP/実装を変えた後に実行する read-only 監査。

Docs ↔ Implementation Consistency Audit

LP・ドキュメント・実装が食い違うと、ユーザーは「書いてあることが嘘」になる。 このスキルは website / docs / README / crates を横断し、主張(コピー)が実装の事実と一致しているかを機械的に点検する。 既定は read-only(発見の報告のみ)。修正は別タスク/別 PR で、合意の上で行う。 一次正典: docs/SPECIFICATION.md、CLAUDE.md §6(Copywriting の論理整合)、§7、メモリ csw-canonical-vocabulary / csw-positioning-desktop-suite / propagate-changes-to-all-surfaces-and-grep。

いつ実行するか

• リリース前、または LP・docs・実装のいずれかを変えた後(/audit-consistency)。
• 用語・アーキテクチャ表現・CLI コマンド・機能主張を変えたとき(伝播確認)。

監査対象サーフェス

• website/index.html(EN LP) / website/ja/index.html(JA LP) / website/style.css
• docs/SPECIFICATION.md(正典) / docs/USER_GUIDE.md(JA) / docs/USER_GUIDE_EN.md(EN) / README.md(あれば ja/en)
• docs/PRIVACY.md(JA) / docs/PRIVACY_EN.md(EN) — 記載の「書く場所・読む場所のパス一覧」「実行する OS コマンド一覧」「open_url に渡しうる固定 URL 一覧」が実装(crates/)と一致するかを必ず点検する。 実装がファイル操作・外部コマンド・URL を増減させたのに PRIVACY 文書が古いままなら blocker (この文書は「実装と同期させている」と自ら宣言しているため、乖離は即、事実に反する主張になる)
• crates/core(ロジック・OSパス・Keychain・環境/シンボリックリンク) / crates/cli(clap のサブコマンド・フラグ)
• crates/desktop/ui/(GUI のユーザー可視コピー: index.html のオンボーディング/カード/ラベル、main.js のボタン文言・トースト・ヒント・モックデータ、style.css)を一級サーフェスとして必ず含める。 crates/desktop/src/(Tauri コマンド・トレイ)も同様。ドキュメント/LP への指摘はアプリへの指摘でもあり逆もそう——アプリ GUI の文言を監査から外すと、実装とドキュメントが食い違ったまま出荷される(過去に実際に発生)。

双方向の原則(超重要): 変更が「ドキュメント/LP 側」「アプリ/実装側」のどちらで起きても、必ず両方向(app → docs/LP と docs/LP → app)で整合を点検する。サンプルコマンド・環境名の例・オンボーディングの説明・ボタンラベル・切替/起動モデルは、アプリ・docs・LP の3面すべてで同じ事実を語ること。[[lp-sample-commands-mark-placeholders]] / [[check-app-and-docs-consistency-both-ways]]。

監査ディメンション(各を独立に点検)

1. 用語の正典(Terminology canon)

   • ユーザー向け呼称は「環境」で確定(プロファイルでない / csw-canonical-vocabulary)。「既存のClaude/利用中」等の正典語が全サーフェスで一致。
   • 旧語・ブレを全リポ grep で残存ゼロ確認(JA/EN 両方)。例: 古い "プロファイル" のユーザー向け使用、"コンテキスト" の混在、他社エージェント名(Antigravity/Gemini/Jules)の残骸。

2. アーキテクチャの真実(Architecture truth)

   • CSW は 2つの別ツール(Claude Desktop App = GUI、Claude Code = CLI)を、共通の環境(プロファイル+Keychain)基盤で隔離/共有する。一方を他方の機能と書かない(CLAUDE.md §6.1)。
   • 何が隔離され(ログイン/履歴等)、何が共有されるかの記述が、crates/core の実装(シンボリックリンク/Keychain 操作の対象)と一致。

3. CLI 表面(CLI surface)

   • docs/LP が言及する csw のサブコマンド・フラグ・例(eval $(csw env) 等)が crates/cli の clap 定義に実在する。
   • 逆に、主要コマンドがドキュメント化されている(実装にあるのに未記載の重要機能がない)。
   • サンプルコマンド内のユーザー依存の引数(環境名・プロファイル名・パス等)が、プレースホルダ化(<環境名> / <env-name>)か即時定義されている。eval $(csw env Work) のように具体名を無定義でハードコードした見せ方を検出する(Work は利用者が付ける名前で、読者が固定トークンと誤解する)。docs の手順は「Work（対象の環境名）」のように具体例+定義でも可。LP/README は無定義ハードコード不可。

4. 機能主張(Feature claims)

   • LP/docs の機能主張(Cowork/Design/Artifacts/Projects/Code 連携、メニューバー管理、ターミナル統合)が実際の挙動と一致。
   • 矛盾するワークフローを書かない(CLAUDE.md §6.2: 端末コマンドが要るのに「設定不要・メニューバーだけで完結」等の包括主張をしない)。

5. ja/en 整合(Localization parity)

   • website/ja ↔ website/index.html が構造的に整合(CLAUDE.md の Multi-language Sync: 構造/レイアウト変更は両言語同時)。
   • USER_GUIDE.md ↔ USER_GUIDE_EN.md が主張・手順で一致。一方だけ古い記述がない。

6. バージョン・導入手順(Version/install)

   • ダウンロードリンク・インストール手順・バージョン参照が一貫し最新。外部ドキュメントCTAは GitHub 等の外部URL(内部アンカー #guide 不可、CLAUDE.md §5 External Documentation Links)。

7. 禁止表現・トーン(Banned patterns)

   • ユーザー可視テキストに ※ / ＊ / 絵文字 / em-dash(—)を使っていない。
   • 生の技術用語(Application Support / Keychain 等)を、利点に翻訳せず露出していない(CLAUDE.md の User-Centric Copywriting)。誇張形容詞("perfect/seamless/smart")なし。
   • 日本語タイポは [[japanese-typography-qa]] のチェックリストにも適合(見出しスケール逆転・折り返し崩れがない)。

実行手順(Workflow でファンアウト)

横断監査は多観点なので、core_ai_workflow に従い Workflow で並列化する:

1. 列挙(自分で): grep/Glob で対象サーフェスと、CLI の clap サブコマンド一覧(crates/cli)、正典用語、機能リストを先に集める。これを各エージェントに渡す。
2. 並列監査(pipeline): 上の 7 ディメンションを 1 エージェント1観点で走らせ、各々が findings[] を {surface, file:line, claim(引用), reality(実装/正典), severity, fix} の構造化で返す。
3. 敵対的検証: 各 finding を別エージェントが「本当に不整合か(実装/正典を確認)」で反証。誤検出(実装にある/正典どおり)は落とす。
4. 統合: 重複を束ね、severity 順に1本のレポートへ。

エージェントには現在日付と「訓練データで即答せず、必ず該当ファイルを Read/grep して一次確認」を明示する([[instruct-agents-with-date-and-verify-latest]])。CLI 表面はソース(clap)を唯一の真実とする。

severity

• blocker: 事実に反する/矛盾する主張(存在しない CLI、隔離範囲の誤り、相反ワークフロー)。
• major: 用語ブレ、ja/en 乖離、未反映の伝播漏れ。
• minor: トーン/タイポ/記号(※・絵文字・em-dash)、軽微な表現。

出力

• severity 別の findings 表(surface / file:line / 主張 / 実装の事実 / 修正案)。
• 「整合済み」も明記(点検したが問題なしのディメンション)。
• read-only。修正適用はユーザー合意の上、別 PR で(変更したら全サーフェス伝播+grep 残存ゼロ確認 / propagate-changes-to-all-surfaces-and-grep)。

追記: プロダクト全体検証と派生物・配布可能性

この監査は「差分だけを見る」のではなく、プロダクト全体を一つの正しい姿として検証するためのものです。以下の観点は上の 7 ディメンションを補強し、テキストに映らない派生物・実行時挙動・配布可能性まで整合の対象に含めます。

1. 非テキスト派生物を明示列挙して再生成する

UI のラベル・レイアウト・コピーを変えたら、それを写した非テキスト派生物を必ず明示列挙し、再生成対象として扱います。テキストの変更は全リポ grep で旧表現の残存ゼロを確認できますが、画像は grep に一切映りません。スクリーンショット・OG 画像・図版に古い文言や旧レイアウトが焼き込まれたまま残っても、テキスト検索では検出できないためです。

検証手順:

• UI/コピーを変える PR では、影響を受ける派生物(オンボーディング/機能のスクリーンショット、LP の OG 画像、docs の図版)をリストアップし、再生成したことを確認する。
• 派生物が古いままなら、実装・docs は正しくても出荷物としては不整合(major)として扱う。
• OG 画像は次の二面を分けて確認する。
  • 中身: メッセージ・モード名・訴求文を変えたら OG 画像も作り直す(古い文言が焼き込まれていないか)。
  • 読み込み: og:image が絶対 https URL を指し、寸法が 1200×630 で、同名アセットを差し替えたときはキャッシュバスター(?v= 等)を上げているか。相対パスやキャッシュ残りはクローラ側で旧画像が表示される原因になる。

2. サンプルコマンドは配布・導入可能性まで検証する

docs/LP に載せる CLI コマンド例は、そのバイナリが対象ユーザーに配布・導入可能かまで検証します。実装(crates/cli の clap 定義)にコマンドが実在するだけでは不十分です。

検証手順:

• 例で呼び出すバイナリ(csw 等)が、対象ユーザーが受け取る配布物に含まれているかを確認する。
• 配布物に含まれないなら、同じ動線の中に導入手順(インストール・PATH 追加等)が示されているかを確認する。
• どちらも満たさなければ、読者が手順どおりになぞってもコマンドが見つからず、サンプルは動きません(blocker)。「実装にある」と「読者が実行できる」は別問題として切り分けます。

これは上のディメンション 3(CLI 表面)の「実在するか」を、配布・導入の一段先まで延長する点検です。

3. 主張と実装の一致は実行時挙動で確認する

docs/LP が「日英対応」「〜モードがある」といった機能主張を掲げるとき、その実体がアプリ本体にあるかをコードまたは実機で確認します。派生物(スクリーンショット・docs の記述)だけを見て「対応済み」と判断しません。スクリーンショットが両言語で用意されていても、アプリ本体が実行時に言語を切り替えなければ、主張は実装と食い違ったままです。

検証手順:

• 「対応している」「モードがある」系の主張を洗い出し、それぞれの実体を crates/desktop / crates/core のコード、または実機(cargo tauri dev 等)で裏取りする。
• 多言語を謳うなら、相手言語でも実際に描画・切替が起きること、かつレイアウトが崩れないことを実機・ヘッドレスで確認する(日本語グリッドは japanese-typography-qa のチェックに従う)。
• 派生物だけが対応済みで実装が伴っていない場合は、事実に反する主張(blocker)として扱う。

4. 禁止記号は出荷前チェックの明示項目にする

上のディメンション 7 の記号規律を、出荷前チェックの独立した確認項目として毎回通します: ユーザー可視テキストに ※ / ＊ / 装飾絵文字 / em-dash(—)を使っていない。該当を見つけたら minor として報告し、、 / ： / （） / 文分割 に置き換えます。眺めるだけで済ませず、—・※・＊ を grep して残存ゼロを実測で確認します。

5. 「存在しない/逆」系の finding は現行 worktree で再検証する

この監査で「その CLI は存在しない」「実装は主張と逆になっている」といった事実系の finding が出たときは、採用する前に現行の作業 worktree で再検証します。監査エージェントの起動 cwd が古い worktree を指していると、最新の実装・コピーを「無い/旧仕様」と誤断することがあるためです。

検証手順:

• 事実 finding(有無・現行形)は、origin/main ベースの現行 worktree 側で対象ファイルを Read / grep し直してから採用する。
• Read/grep で開く絶対パスが現行 worktree 配下を指しているかを確認する。
• 文章・論理・トーンの指摘(記号規律・矛盾ワークフロー・用語ブレ等)は cwd に依存しないため、そのまま採用してよい。cwd 依存で偽陽性になりうるのは「実装にあるか/現行形か」を問う事実 finding に限られる。