これは何か

この repo は kouchou-ai 本体ではなく、開発者向け Wiki / 調査ノート / 文脈整理のための補助 repo である。
そのため実務では、

  1. この repo の wiki/ で過去議論や設計判断を整理する
  2. work/kouchou-ai/ に置いた local clone(HEAD は main のまま)で本体コードを読む・試す。直す時は、同じ clone から作った別 worktree(work/kouchou-ai-<topic>/)で作業する
  3. 最終的なコード変更は digitaldemocracy2030/kouchou-ai に commit / PR する

という 二層運用 になる。source-codeより

なぜこうなっているか

kouchou-ai 本体 repo だけを見ても、

  • 過去の議事メモ
  • Slack 上の設計意図
  • main と open PR の差
  • docs と実装のズレ

が散在していて、新規コントリビュータや AI エージェントが文脈を掴みにくい。
この Wiki repo は、その不足を補うために 「いまのコード」と「過去の判断理由」をつなぐ中間層 として作られている。meeting-minutes / github-dev-docsより

典型的な流れ

1. 文脈整理は Wiki repo 側でやる

  • raw/ に source を置く
  • wiki/ に source / concept / analysis を追加する
  • log.md の先頭に ingest / filing-back の entry を足し、python3 scripts/refresh_logs.py で log.txt と log.md を同期する(lint で問題を見つけて直した時は filing-back として書く。問題が無かった lint は書かない)

つまり、「何が論点で、なぜそう判断されたか」 を残す作業はこの repo の責務。source-codeより

公開 Quartz サイトでの見え方(URL と表示タイトルの分離・Explorer のラベル)の規約は quartz-site-presentation にまとめている。

2. 実装確認は work/kouchou-ai/ を一次参照にする

work/kouchou-ai/ はこの repo 配下に置いた local clone で、コード由来の判断はここを一次参照にする。
docs/ や DeepWiki は補助線であり、実装断定は local clone を優先する。更新前には git fetch origin && git pull --ff-only を行い、参照 commit をメモする。source-codeより

3. コード変更の提出先は本体 repo

実際にコードを直す時も、work/kouchou-ai/ は main のまま(読む・確かめる専用)にしておき、同じ clone から別の worktree を作って、そこで commit / push / PR を行う。複数の作業(AI エージェントのセッションなど)が同じ clone を同時に参照していることがあり、work/kouchou-ai/ で branch を切り替えると、他の作業が main を読んでいるつもりで別 branch を読む事故が起きるためである。CLAUDE.md より

git -C work/kouchou-ai fetch origin
git -C work/kouchou-ai worktree add --no-track -b <branch> ../kouchou-ai-<topic> origin/main
cd work/kouchou-ai-<topic>
pnpm install --frozen-lockfile   # Git hook(lefthook)をこの worktree にも入れる
# 変更・commit のあと
git push -u origin <branch>

--no-track を付けないと新しい branch の上流が origin/main になり、引数なしの git push が失敗する。本体 repo に push 権限が無い場合は、自分の fork を remote に足してそちらへ push し、PR を出す。worktree ごとに pnpm install が要る理由は worktree-hygiene を参照。

したがって、作業場所は Wiki repo でも、提出先は digitaldemocracy2030/kouchou-ai になることがある。これはこの運用では普通であり、むしろ想定された使い方。contributingより

「調べて」と言われた時の最新ソース確認順

この repo では、質問に答える前に 「どのソースが一次で、どう最新化するか」 を切り分ける必要がある。単に既存 Wiki ページを読むだけで済ませない。

情報鮮度の基準

Wiki の情報鮮度は、ページの編集日時ではなく 対象 source をいつ時点まで読んだか を基準に読む。特に議事録 Google Doc と Slack log は追記され続けるため、source ページ側に「最終取得・読解日」「対象期間」「対象 channel / raw snapshot の有無」を明示する。nishio-source-freshness-criterion-2026-06-02より

  • 議事録は meeting-minutes の freshness marker を見る。Google Doc export を最後に取り直した日、先頭見出し、txt / html の取得有無が基準になる。
  • Slack は slack-logs-repository と各 Slack source の freshness marker を見る。直近(raw の最新月と重なる rolling window。2026-10 時点で 75 日。範囲は mirror/sync.json の window_days / window_oldest で確かめる)は digitaldemocracy2030/slack-logs の mirror/、それより古い public channel log は同 repo の raw/ を優先し、2026-10-21 週までの週次 AI 要約や GitHub 活動まとめは oss_weekly_reporter を補助線にする(2026-10-22 に更新停止。2026-10-21 週までの過去分のみ。Slack 本文は全期間 slack-logs の raw/ に埋め戻し済み)。
  • 最新確認なしで答える場合は、「この Wiki では <marker> 時点まで観測」として扱い、現在進行形の状態を断定しない。最新状態が論点なら source を再取得してから答える。

コード本体について聞かれた時

まず work/kouchou-ai/ の local clone を git fetch origin && git pull --ff-only で最新化し、参照 commit を残す。docs/ や DeepWiki は補助線であり、実装断定の根拠にはしない。source-codeより

議事録について聞かれた時

まず Google Doc export から raw/meeting_minutes.txt を取り直す。既存の meeting-minutes 要約があっても、更新前に raw を refresh する のが前提。なお txt export は検索向きだがリンク URL を落とすことがあるため、URL 自体が必要な質問では raw/meeting_minutes.html も併読する。meeting-minutesより

Slack の発言について聞かれた時

まず work/slack-logs/ を git pull --ff-only で最新化し、mirror/sync.json の synced_at / window / channel 数を確認する。直近(2026-10 時点で 75 日。raw の最新月と重なるよう設定されている)は mirror/slack/<channel_id>.jsonl.gz、それより古い月の stable な根拠は raw/slack/<channel_id>/<YYYY-MM>.jsonl.gz を読む。raw は約 2 か月遅れるので、mirror を直近 14 日分だけ読んで raw に移ると、その間の発言を見落とす。mirror/ は上書きされるので、重要な観測を wiki に残す時は commit hash、synced_at、window、channel ID を併記する。slack-logs-repositoryより

message の user は Slack user id なので、発言者が論点になる時だけ mirror/users.json または同月の state/users-YYYY-MM.json で表示名に解決する。通常の filing-back では raw 発言者名より、channel / 日付 / 論点 / source freshness を残す方が安全で再利用しやすい。

週次の流れを掴む、または GitHub activity と一緒に見る時は oss_weekly_reporter の ai_reports/ と既存 weekly-log-* source を補助線として使う(2026-10-22 に更新停止。2026-10-21 週までの過去分のみ。Slack 本文は全期間 slack-logs の raw/ に埋め戻し済み)。古い source は「どの週まで観測済みか」を含めて扱う。weekly-log-2026-05-06より

GitHub の現在進行形について聞かれた時

main だけでは不十分なことがあるので、open PR や issue も併せて確認する。未マージ作業は main に出ないため、現在の論点整理では gh pr list -R digitaldemocracy2030/kouchou-ai --state open のような観測が要る。CLAUDE.md より

security / dependency 系の話題では、GitHub Security の Dependabot alerts (https://github.com/digitaldemocracy2030/kouchou-ai/security/dependabot) も live state として扱う。これは main clone や open PR 一覧だけでは拾えないため、定期的な保守観測に含める。ただし alert の具体的な脆弱性詳細は公開 wiki に転記せず、対応 issue / PR / 優先度判断だけを残す。2026-06-01 定例では Actions / CodeQL / Dependabot 警告が優先対応対象として共有されていた。meeting-minutesより

公開 wiki に書かない情報

この repo の wiki/ は GitHub Pages で公開されるため、公開境界を先に決める。

  • Dependabot alerts の具体的な脆弱性詳細は公開 wiki に書かない。確認した事実を残す場合も、対応 issue / PR / 優先度判断 / 担当確認の粒度に留める。
  • Azure デモ環境などのデプロイ詳細は公開 wiki に書かない。実環境 URL、resource 名・サイズ、revision / run の詳細、ログ、具体手順、secret / access 周辺の情報は載せない。
  • デプロイ詳細の一次置き場は Google Drive の 「広聴AI-Azureデモ環境」。アクセス権は大木・西尾・小野(moai)。公開 wiki からは、設計判断・公開可能な課題・対応 issue / PR だけを参照する。

これは「観測しない」という意味ではない。AI エージェントやメンテナは必要に応じて live state / private source を確認するが、filing-back する時に公開粒度へ落とす。CLAUDE.md より

答えた後

有用な整理が生まれたら wiki/analyses/ や既存 concept / source に filing-back し、wiki/log.md に記録する。
つまりこの repo の Query は「その場で答える」だけでなく、再利用可能な知識へ還流するところまで が 1 セット。CLAUDE.md より

長い AI goal の速度制御

Codex /goal のように persistent な goal を広い目的で走らせる場合、この wiki-driven workflow をさらに強く使う。2026-06-30 Slack では、広聴AIに Codex /goal を使う案と同時に、人間が追いつけなくなるため、まず状況把握と LLM Wiki / docs 更新を中心にする方針が共有された。slack-codex-goal-speed-control-2026-06-30より

この運用では、AI の最初の成果物は PR ではなく、人間が次の PR / issue / demo / docs を選べる状態である。

  1. work/kouchou-ai/、work/slack-logs/、必要な raw source を最新化する。
  2. current main、open PR / issue、Slack、議事録を同じ snapshot として読む。
  3. source / analysis / concept / meeting draft を更新し、未決論点を thinking-targets へ寄せる。
  4. 本体 repo の code PR に進む時は、assignee / ownership / human attention を確認してから小さい slice を切る。

これにより、AI が速く進みすぎて「何を見て何を決めたか」を人間が追えなくなる問題を避けられる。

繰り返しタスクを agent 化する時

2026-06-23〜06-30 の Slack では、毎週の議事録を見て Web サイトを更新するような繰り返しタスクを Devin 化できると、Web サイトを活発に保てそうだという案が出ている。これは wiki-driven workflow の自然な応用だが、公開面を直接触るため、先に contract を切る必要がある。slack-devin-ops-and-recurring-web-updates-2026-06-30より

最小 contract は、議事録 export / Slack mirror をいつ時点まで読んだか、公開 wiki / website に書いてよい粒度か、どのページが canonical か、人間 review owner は誰か の 4 点である。AI agent は source freshness と draft diff を作るところまでを担い、掲載許諾・外部向け表現・merge は人間判断に残す。

誤解しやすい点

「Wiki repo で作業しているなら、この repo に PR を出すのでは?」ではない

文脈整理しかしていないなら、この repo に commit / push するだけで終わる。
しかし調査結果をもとに kouchou-ai 本体のコードや docs を直すなら、PR の提出先は本体 repo になる。「いま見ている repo」と「最終提出先 repo」が一致しない のが、この運用の特徴。source-codeより

CLA は提出先 repo に従う

最終的に digitaldemocracy2030/kouchou-ai に PR を出すなら、作業の起点がこの Wiki repo でも CLA は必要。
逆に、この Wiki repo にだけ commit して終わるなら kouchou-ai の PR テンプレートや CLA 節は直接は出てこない。判断基準は 「どこで作業したか」ではなく「どこへ PR を出すか」。contributingより

work/ は生成物ではなく、長く参照する clone の置き場

/tmp は ephemeral なので、継続的に参照したい clone は work/ に置く。
Wiki repo の work/ は「補助 repo の中に本体 repo の local clone を同居させる」ための意図的な構造であり、場当たり的なディレクトリではない。source-code / CLAUDE.md より

向いているケース

  • 仕様や背景を整理してから本体 repo に手を入れたい時
  • 議事メモや Slack の設計意図を Wiki に残しつつ実装変更したい時
  • AI エージェントに「まず文脈を掴ませ、その後に本体 repo を直させる」時

この repo 自体の公開方法

この repo の wiki/ は docs 置き場というより knowledge base / digital garden に近いので、GitHub Pages 配信も単なる Markdown renderer ではなく wikilink 中心の公開体験で選ぶ方が自然である。現在は wiki-pages-publishing-stack の判断どおり、wiki/ を直接読む Quartz 構成で GitHub Pages 配信している。wiki-pages-tooling-observation-2026-05-21より

この repo 自体の更新は、原則として main への直接 commit / push で扱う。kouchou-ai 本体の変更と違い、developer-wiki の運用メモや表示調整を毎回 PR 経由にすると知識還流の速度が落ちるためである。2026-05-25 には一時的に GitHub 側の Internal Server Error で git push origin main が拒否されたが、main が unprotected かつ fast-forward 可能な時だけ gh api ... git/refs/heads/main ... force=false で直接進める fallback とした。退避 PR は例外扱いで、通常運用にはしない。wiki-maintenance-observation-2026-05-25より

向いていないケース

  • 単純な typo 修正だけで、文脈整理や調査が不要な時
  • 本体 repo だけ見れば十分で、Wiki への filing-back 価値が薄い時

関連

Open Questions

  • この運用を新規コントリビュータ向け onboarding の標準フローとして docs に昇格させるべきか
  • 議事録から Web サイトを更新する繰り返し agent task の canonical page / review owner をどこに置くか
  • work/ に複数 clone がある時の命名規約をどこまで固定するか — kouchou-ai の branch 作業は別 worktree work/kouchou-ai-<topic>/ で行う形で決着済み(CLAUDE.md、2026-05-29)。残るのは <topic> の付け方と、使い終わった worktree を片付ける方針
  • pnpm check が work/ 配下 clone を拾う状態を tsconfig.json 側で直すか

Updates

  • 2026-10-21: 本体コードを直す手順を、work/kouchou-ai/ は main のまま保ち、別 worktree(work/kouchou-ai-<topic>/)で branch を切る形に訂正(CLAUDE.md の運用ルールに合わせた)。log に残す entry を ingest / filing-back に訂正(問題が無かった lint は記録しない。2026-05-26 からの CLAUDE.md の lint 記録ポリシー)。あわせて、Slack mirror の窓を 14 日から 75 日(2026-08-21 に slack-logs 側で変更)に訂正
  • 2026-06-30: slack-devin-ops-and-recurring-web-updates-2026-06-30 を追加し、議事録から Web サイトを更新する繰り返し agent task は source freshness、public boundary、canonical page、human review owner を先に決める必要があると追記
  • 2026-06-30: slack-codex-goal-speed-control-2026-06-30 を追加し、persistent goal はまず状況把握・wiki / docs 更新・thinking-targets 整理を行い、人間が次の slice を選べる状態を作る運用を追記
  • 2026-05-19: 初版作成
  • 2026-05-19: 「コード / 議事録 / Slack / GitHub」を調べる時の最新ソース確認順を追記
  • 2026-05-23: GitHub Pages 配信の説明が MkDocs 時代の比較文のまま stale だったため、Quartz 配信中の current state に更新
  • 2026-05-25: 議事録 query で txt export がリンク URL を落としうる点と、html export を補助線にする運用を追記
  • 2026-05-25: developer-wiki 自体の更新は PR 経由にせず、main 直接 push を基本にする運用を追記
  • 2026-06-01: Dependabot alerts を GitHub current state の定期観測対象として追記。公開 wiki には脆弱性詳細を転記しない方針も明記
  • 2026-06-01: 公開 wiki に Dependabot 脆弱性詳細とデプロイ詳細を書かない境界を追記。デプロイ詳細の一次置き場を Google Drive「広聴AI-Azureデモ環境」と明記
  • 2026-06-02: 議事録 / Slack の情報鮮度は「いつ時点まで source を読んだか」を基準にし、source ページに freshness marker を明示する運用を追記
  • 2026-06-30: Slack raw の最新一次参照を digitaldemocracy2030/slack-logs の mirror/ / raw/ に更新し、oss_weekly_reporter は週次 AI report / GitHub report 補助線として位置づけ直した
  • 2026-06-30: Slack message の user id 解決は mirror/users.json / state/users-YYYY-MM.json を使うが、wiki へは発言者名より channel / 日付 / 論点 / freshness marker を優先して残す運用を追記

Updates — 2026-09-07 公開サイトのリンク生成疑い

公開サイトで https://nishio.github.io/concepts/wiki-driven-workflow(base path 欠落 URL)にアクセスできず、検索結果または Explorer 由来のリンクが切れている可能性が観測された。正しい公開URLは https://nishio.github.io/kouchou-ai-developer-wiki/concepts/wiki-driven-workflow でHTTP 200を確認済み。検索 / Explorerのどちらが誤URLを生成したかは未再現・未特定であり、手入力の誤りと断定しない。次回は公開サイト上でリンク生成元とproject base pathの扱いを確認する。

2026-09-07 公開リンクの再現確認と修正

公開Chromeでトップ→Explorer concepts→wiki-driven-workflow、個別ページの検索→contributing→再検索を確認し、いずれもproject base pathを含む正しいURLとなった。元のbase path脱落はこの経路では再現しない。

一方、Pagesの直近失敗ログでは labelling-prompt-few-shot-template-confound-2026-06-03 の非公開raw artifactへの相対リンクがbase pathを抜け、生成リンク検査を失敗させていた。公開サイトは6月5日の内容で止まっていた。リンク検査を緩めず、対象をローカル保存先のコード表記へ修正して公開を復旧する。

Updates — 2026-09-09 01:44 実装とIssue整理を次の判断へ還流する

other-issue-candidates-2026-09-07 の両版への実装と issue-backlog-audit-2026-09-09 の棚卸しから、次回にも使う判断を三点にまとめる。作業件数・各PR・テスト結果は各記録の観測時点に基づき、このfile backではGitHub・コード・実モデルの再観測はしていない。

  1. Issueの完了は、合意した利用者の行動と現行mainで判断する。 古いコメントや類似機能の存在は調査の入口にする。#513の「seed設定済み」は、その後の意図的な固定除去で現在の根拠ではなくなっていた。#79 / #11は作成前確認画面があっても見積もりが「目安なし」であり、#56は抽出意見を読めても元コメントへ戻る要件が残る。close時は満たした範囲・根拠commit / PR・確認方法を残す。重複は未解決の要件を存続Issueへ移し、統合先を示して閉じる。
  2. 確認できた性質を、より広い保証へ膨らませない。 #514では並列処理を意図的に逆順で完了させ、出力が入力順に戻ることを確認した。この試験はLLM出力やクラスタの再現性を保証しない。同様に、チャット接続成功、単体試験成功、ブラウザでの失敗後の復帰、実モデル確認、CI成功、main反映をそれぞれ区別する。#912 / #913の実モデル確認はユーザー指定の人間担当として残す。
  3. Serverlessとは同じ入力・期待する振る舞い・復帰操作を照合する。 #528では両版の図と説明について、同じ属性条件で件数・割合・移動・全体への復帰を確認した。#566の合成12意見の状態カタログも両版の空・通常・エラー等を比較する材料になる。一方、本体の静的出力はHTTP配信、Serverlessの単一HTMLは直接開けるという配布上の差は保持する。共通化は利用者の仕事を成立させるために行い、本流化やrepo移管の決定を前提にしない。

Issueをまとめて更新する際は、読み取った本文・更新時刻と操作案をlocal snapshotに残し、書込直前に変更の有無を照合する。変更されていれば再読解し、反映後には本文・状態・統合先を再取得して確認する。今回の記録先は raw/issue-audit-2026-09-09/。公開Wikiには判断と公開Issueへの参照を残す。issue-backlog-audit-2026-09-09より

Updates — 2026-10-10 別環境への委譲でもWikiを作業の起点にする

issue-backlog-audit-2026-09-09より、別環境のエージェントへ古いIssue調査を渡す指示文で、Wikiのcloneと知見の書き戻しが任意になっていた。西尾の指摘を受け、委譲先でもdeveloper-wikiを作業ディレクトリにし、既存判断の読解、本体のwork/内での検証、source/analysisへの還流、定例報告・ログ、mainへのcommit/pushまでを一つの完了条件にした。

タスクキューは依頼・状態・判断待ちを受け渡し、成果のWikiページとcommitを指す。知見の正本をキューや一時レポートに分散させない。gitignoredのraw/workがcloneで届かない点と、一次証跡を別環境から回収できる保存先を持つ点も引き継ぎに含める。

Updates — 2026-10-10 委譲は受信側で確認する

issue-backlog-audit-2026-09-09より、Wikiに委譲の準備を記録してpushしても、実行側のキューには依頼が届いていなかった。指示文の準備、依頼キューへのpush、受信側のclone・台帳登録・一覧表示、ワーカーの実際の起動、成果の共有を別の状態として確認する。受信側と送信側のcommit・指示文hashを照合し、起動待ちを実行中や調査完了と報告しない。