kouchou-ai developer wiki

broad-listening-book-extractions

14 min read

book source を読み、今後の開発に効く 知見だけを抽出する。書籍そのものの目的（広い読者層への解説）から外れて、コードに触れる人間が知るべき項目を選んでいる。

1. すでに本 wiki にあった主張の「出版可能形」での裏付け

これまで Slack / 議事メモ / 個別観察ベースで wiki に書かれていた以下の主張が、書籍 13 章で 公開可能な確定版 として整理された。今後 PR レビューで「この設計はなぜか」と聞かれた場合、書籍を引用すれば足りる。

  • K-means を選んだ理由は精度ではなく「散布図と直感の一致」（10_00, 13.2.4）。Spectral Clustering で発生した「飛び地」が日テレ 2024 衆院選特番の散布図に観測されている図つき。→ pipeline の「なぜ UMAP→クラスタリングなのか」を補強
  • UMAP の 2D 結果でクラスタリングしているのは標準作法とは異なる妥協 であることを 13.2.4 が明示的に認めている。「散布図とクラスタ分けの見た目を一致させる」設計判断と、自由記述抽出後のデータは情報が圧縮済みなので精度向上が限定的という経験的観察を二つの根拠として挙げる
  • ∛n / n^(2/3) の指数は理論最適値ではなく経験値（13.4.2）。視認性基準で試行錯誤の末に落ち着いた値。実務利用ではもっとクラスタ数を増やすべき場面があると本書自身が認めている。→ auto-cluster-defaults の補足になる
  • KJ法 / 表札 という日本語専門用語を使うことでラベリング品質が上がる（13.2.6）。プロンプトに専門用語を載せるという作法の根拠
  • シルエットスコア等の自動最適化を採用していない理由（13.4.2 脚注）: 利用者が「見たい粒度」を選べる方が実用的、自動最適化が必ずしも「望ましいクラスタ数」を返さない。→ pipeline と umap-seed-history の補強

2. 現場運用で繰り返された具体的な障害／要望（既知 issue と未対応のものを分ける）

すでに見えていた / 部分対応済み

  • ラベルが抽象すぎる (朝日新聞 04_05, 東京都 05) — 編集者が手で書き直す運用が常態化していた。朝日新聞の対策は「見出しを 5 つ付ける」プロンプト改造。広聴AI 側ではプロンプトに「具体的な事象・行動を含めてください」「抽象的な表現は避けてください」と書き込んでいる（13.2.7）が、運用者が依然として手で再ラベルする実態がある
  • クラスタ数のジレンマ: 少ないと抽象的、多いと読者に伝えきれない（朝日新聞 04_05、都 05 はどちらも 40-50 クラスタで詳細を見たがる）。∛n デフォルトは「見栄えのする図」基準。実務寄りのプリセットも要りそう
  • source-link / トレーサビリティ はチームみらい版で追加され本流に還元された（10_00）。「AI 出力を鵜呑みにせず元の発言まで戻れる」ことの設計上の重要性

未対応 (≒ 開発機会)

  • off-topic 大クラスタ問題 (朝日新聞 04_05, 都 05) — 「全意見を散布図に載せる」ため、テーマから外れた意見が最大クラスタになって報道で扱えない、というクレームが複数現場から出ている。朝日からは明示的に「外れ値除外機能」が要望されている。広聴AIには「濃いクラスタ抽出」はあるが、これは「密度ベースの足切り」であり「テーマ適合度の足切り」ではない。LLM による on/off-topic 判定で抽出時にフィルタする機能は未実装と見られる
  • SNS データ取得のキーワード設計が一番難しい (朝日新聞 04_05) — ブロードリスニング以前の問題だが、kouchou-ai が SNS データを扱うユースケースで現場が再発明する作業。X / YouTube 取得とキーワード設計のテンプレート化や input plugin 化 (plugin-system) は機会
  • ローカル実行可能な UI が報道機関側で求められている (朝日新聞 04_05) — OpenAI API はセキュリティ契約下で使えるが、「他社サーバにデータを上げる」のはハードルが高い。広聴AI の自治体向けセルフホスト要件と完全に一致する観点。LocalLLM 対応 (PR #824 ほか) が継続的に重視されるべき根拠
  • アンケート vs SNS でクラスタリング品質に明確な差 (朝日新聞 04_05) — 一定方向性が定まったアンケート由来は綺麗、SNS は乱雑。input plugin / config で「想定する分布の整理度」を宣言する設計の余地

3. 既存実装になく書籍が「次に手を入れる」と示している領域

賛否分離 (13.4.3)

  • アプローチ1: センチメント次元の付与 — 抽出時に LLM が -1.0〜+1.0 のスコアを推定、エンベディングに重み付きで連結。電力政策パブコメ約 1,000 件で weight=0.75 にすると風力発電クラスタが賛否で分離した図あり。weight が大きすぎるとトピック類似性が消える、というトレードオフが書かれている
  • アプローチ2: DivCon (Divide and Conciliate) — エンベディング非使用。LLM でトピック発見 → 意見分類 → 対立軸発見 → アンカー生成 → スコアリング。強硬意見が上位に並ぶ「対立ビュー」の出力例あり

開発判断としては、これらは analysis_mode=llm_grouping 系の枝に整合する（pr-827-llm-grouping-capabilities-plan-2026-05-18）。書籍は将来研究テーマとしてしか書いていないが、kouchou-ai の plugin / analysis_mode 設計はこのプロトタイプを内包できる構造になりつつある

Long Context アーキへの選択肢 (13.5)

  • 当初 4,096 トークンしか入らなかったから embedding + UMAP の構成にした、というのが歴史的経緯。100 万トークンが当たり前になった現在、「LLM に全部渡す」TTTC Turbo / LLM 直接グルーピング / 富士通-中央省庁実証実験のアーキも実用域に入った
  • 散布図タイプとロングコンテクストタイプの長短：
    • 散布図タイプ — 「意見の地図」が自動生成、直感的、ただし 2D 圧縮後クラスタリングなので精度が悪い
    • ロングコンテクストタイプ — 賛否分離・ニュアンス区別に強くクラスタリング精度が高い、ただし見栄えのする散布図が出ない
  • 両タイプの併走（mode 切替）が「理想的」と本書も明記。→ pipeline の analysis_mode 戦略を裏付け

4. 「合意形成」設計に関する meta-insight

column/1万件の声を集めて気づいたこと (青山柊太朗) は kouchou-ai が暗黙に依拠している前提を覆す指摘。要約：

9,688 件の提案を集めた。1 万件近い質問に答えた。それらが政治的意思決定の根幹にある利害調整の材料になったかと問われれば、正直に言えばなっていなかった。集まったものの多くは「断片的な立場表明」にとどまっていた。

  • 「声を届ける」と「意思決定に繋げる」の間にギャップがある
  • 合意形成のボトルネックはスケールではなく自己理解。3 人の社内会議でも自己理解不足で対立する
  • 戦略は「スケールアップ」（1 億人の意見集約）から「スケールアウト」（同じ品質の対話を多現場で）へ
  • 太田市の自分ごと化会議では事前に AI 対話で自己理解を掘り下げてから 20 人の住民会議に臨む構造を採用

開発上の含意：

  • kouchou-ai は「集める／分類する／可視化する」の下流に集中していて、上流の自己理解支援（idobata のようなインタビュー系プロダクト）と組み合わせて初めて意思決定に効く
  • 集めた意見の 質 を測る指標（断片度／立場と理由の分離度）を args.csv のメタ列として持つ余地。これは 12.4.8 の Structured Output で実装可能
  • 散布図 UX の固有価値（column/安全な共感）= 反論不能な距離からの観察 = エコーチャンバー解毒、というのは UI の存在理由を強化する根拠でもある

5. すでに wiki にあるページとの差分の取り扱い

既存 wiki ページ書籍が新しく与える情報
pipelineプロンプト全文、設計トレードオフの「公開版」確定、賛否分離プロトタイプ、∛n の経験的根拠
broadlisteningScatter vs Long Context 二アーキの整理、Polis/vTaiwan/Remesh/Birdwatch の比較材料
auto-cluster-defaults∛n は理論最適値ではないという書籍側の明言。実務向けはクラスタ数を増やしたい場面がある
dd20302025-05 のリソース崩壊と Devin/Copilot Agent による下支え、属性フィルタ 2203 行の出自
talk-to-the-cityTTTC Scatter からのフォーク経緯、Scatter vs Turbo の関係
refactoring-status直接の更新材料は薄い。書籍は出版前確定版で 2026-Q1 以降の analysis-core 化を扱わない
plugin-systeminput plugin / analysis plugin の根拠として SNS データ取り込み・LLM 分類差し替えの現場要求

Open Questions

  • 書籍 13 章のプロンプトと、現行 packages/analysis-core/.../prompts/ の文言が一致しているかは未確認。後で diff を取って差分があれば gotchas / pipeline に反映
  • DivCon / sentiment-dim プロトタイプの実装が tokoroten/farbrain その他にどこまで残っているか未調査
  • 「off-topic 大クラスタ」を解決する on-topic フィルタが既に Issue / PR にあるかどうかの確認（書籍記述が要望どまりなのか実装があるのか）

Updates

  • 2026-05-21: 初回作成
  • 2026-05-25: 13.2.6 の「KJ法 / 表札 プロンプト」言及は prompt engineering tips としてだけでなく、product 設計原則として読み直せる。詳細は kj-method-broadlistening-framing-2026-05-25。原文復帰・既存カテゴリ非適用・表札の人間吟味・少数残存・対立/因果構造・現場返却の 6 原則のうち、current kouchou-ai は前 2 つを達成、後ろ 4 つは未達という棚分け
  • 2026-05-25: 13.2.4 の「UMAP 2D でクラスタリングしているのは標準作法と異なる妥協」自認は、外部 deep-research でも裏付けられた。同時に「clustering 用 UMAP は 15D〜25D」「BERTopic は backbone へ位置がずれた」など、書籍時点になかった現代的な落としどころが整理された。詳細は clustering-deep-research-findings-2026-05-25

グラフビュー

バックリンク