kouchou-ai developer wiki

contributing

12 min read

基本フロー（CONTRIBUTING.md）

  1. Issue を立てる
  2. 実装計画を投稿し、メンテナのリアクションを待つ
  3. リアクション後にコード着手
  4. PR を出す

「先に PR」は強く非推奨。CONTRIBUTING.md：合意なしの新機能 PR は マージされない傾向 がある。

ただし、実際の作業は この Wiki repo で調査・整理しつつ、work/kouchou-ai/ で本体コードを触り、最終的に digitaldemocracy2030/kouchou-ai に PR を出す 形になることがある。これは例外ではなく想定された運用。全体像は wiki-driven-workflow を参照。

まず利用モードを判定する

2026-05 時点では、PR や issue を読む前に それがどの利用モードの改善か を切るとレビューしやすい。詳細は usage-modes。

  • Web UI: admin / api / public-viewer / 公開・共有・ホスティングに効く変更
  • CLI / analysis-core: packages/analysis-core/ / kouchou-analyze / PyPI / 中間成果物 / report.html に効く変更
  • 共通基盤: パイプライン品質、provider 対応、plugin 基盤、旧コード削除のように両方へ効く変更

この切り分けを先にしておくと、PR #825 のような「CLI では重要だが Web の主経路は変えない」変更を、Web 機能の未反映として誤読しにくい。

CLA

CLA.md：すべての貢献に CLA 署名が必要。PR テンプレが合図。

重要なのは、「どの repo で作業したか」ではなく、「digitaldemocracy2030/kouchou-ai に PR を出すか」で決まる こと。たとえば本 Wiki repo やローカル scratch で調査・下書きをしていても、最終的に kouchou-ai 本体へ PR を出すなら、kouchou-ai 側 PR テンプレートの

## CLAへの同意
- [x] CLAの内容を読み、同意しました

を本文に入れる必要がある。PR 本文を独自に組み立てるとこの節を落としやすい ので、AI エージェント経由でも人間経由でも submit 前に確認した方がよい。github-dev-docsより

レビュー方針

CODE_REVIEW_GUIDELINES.md および meeting-minutes 2025-05 〜 2025-07：

  • レビュアー不足は慢性的な問題（特に FE。なのくろさんが polimoney に移動して以降）
  • ohki-shingo が「A: スキルセット / B: 工数 / C: 環境 / D: 基準なし」というマトリクスで分類を試行
  • OS × LLM プロバイダの組み合わせ爆発で全マトリクスのテストは不可能 — 「壊れても良い」許容範囲をどう設計するか が継続課題
  • 2025-05-07 以降「壊れても OK」のスタンスが採用されたが、具体的なマージ基準は PR テンプレ以上には固まっていない

実務上の入口としては、まず 利用モード を見て、その次に 差分の大きさ と 必要な確認環境 を見ると迷いにくい。

  • Web UI PR: admin / public-viewer / build / preview / 共有 UX を重点確認
  • CLI / analysis-core PR: config、生成物、再現性、PyPI / CLI 挙動、データ件数依存の挙動を重点確認
  • 共通基盤 PR: 両モードへの波及、出力スキーマ互換、deprecated 経路への影響を重点確認

PROJECTS.md

ボード運用とその自動化（sasano さん）：assign / unassign / /ready / /archive などの bot 動作が定義されている。

Open PR の見方

main だけでは「いま進んでいるが未マージ」の情報が落ちる。現在の作業状況を見るときは open PR を併用する：

gh pr list -R digitaldemocracy2030/kouchou-ai --state open

2026-05-17 時点で、少なくとも以下が open だった：

  • #825 self-contained HTML report + --without-html 修正
  • #824 LOCAL LLM の full URL / LOCAL_LLM_API_KEY 対応
  • #817 CodeQL / CodeRabbit 設定調整
  • #823, #822 Dependabot による Next.js 更新

つまり、Wiki 上で「未完了」「未反映」と書くときは main に無いこと と open PR に存在すること を区別する必要がある。

加えて、open PR を見たら最初に次の 2 つを切ると読み違いが減る。

  1. どの利用モードの改善か
    Web UI / CLI / 共通基盤
  2. その変更は主経路を変えるのか、補助出力 / 補助経路の改善なのか
    例: PR #825 は CLI 向け観察用HTMLの改善であり、Web の主経路変更ではない

AI エージェントや人間が作った draft PR は、そのまま merge 対象とみなさない 方が安全。少なくとも 2026-05-18 の運用では、draft は「まだ merge 手順に入っていない作業中の状態」と解釈し、ready for review に切り替えてから review / merge 判断に進むルールを置くのがよい。特に AI エージェント起点の PR は「一度 draft で出し、人間が内容を見て ready にする」方が事故が少ない。coding-agentsより

review 対応を push する時は、PR metadata 上の head branch 名 と remote に branch 実体があるか を両方確認した方がよい。2026-05-18 の観測では #824 #825 #826 はそのまま update できた一方、#794 は PR metadata 上の head branch 名が残っていても remote branch 実体が消えており、close + recreate が必要だった。open-pr-observation-2026-05-18より

AI エージェントが PR を扱う場合は、人間 reviewer の request や approval 催促を独断で行わない というルールも必要である。2026-05-21 の PR #849 では、Codex が技術的には reviewer request を送れてしまったが、オーナー判断ではこれは不適切だった。REVIEW_REQUIRED を見た AI は reviewer を足すのではなく、「review が blocker です。誰かに依頼しますか」まで報告して止まる 方がよい。pr-849-agent-review-request-observation-2026-05-21より

Dependabot など bot PR の head を更新した後は、CI が全部 green でも reviewDecision: REVIEW_REQUIRED に戻って merge が block されることがある。2026-05-18 の #823 では、checks 通過後も通常 merge は通らず、approval を入れ直してから merge した。「CI success = すぐ merge 可能」とは限らず、review requirement も見直す。pr-823-review-observation-2026-05-18より

一方で 2026-05-18 の #824 では、checks success と reviewDecision: REVIEW_REQUIRED が併存したままでも、gh pr merge --admin は成功した。つまり 通常 merge 可否 と admin merge 可否 は分けて見る必要がある。owner が片付ける前提の PR triage では、この差を意識した方が実態に合う。pr-824-admin-merge-observation-2026-05-18より

そのうえで、実際の merge 手順としては 1. merge してよい理由を短く comment / review に残す → 2. approve → 3. 通常 merge を試す → 4. それでも保護ルールだけが残る時だけ admin merge が望ましい。技術的に admin merge 可能でも、理由を書かずに押し切ると後から判断根拠を追いにくい。加えて、この 2〜4 の判断は AI ではなく owner / maintainer の明示指示 で進める方が安全である。pr-824-admin-merge-observation-2026-05-18より pr-849-agent-review-request-observation-2026-05-21より

Codex など AI エージェントが review comment や approval comment を残す時は、後から人間が監査しやすいよう by Codex のような署名を付けた方がよい。PR 上で「誰がどう判断したか」を区別しやすくなる。pr-823-review-observation-2026-05-18より

また、2026-05-18 の snapshot では nishio 以外の人間 authored open PR は #734 と #597 の 2 本だけ で、どちらも古い draft かつ mergeable: false だった。棚卸しの詳細は non-nishio-human-pr-status。open-pr-snapshot-2026-05-18より

メンテナ・コミッタ

時系列（meeting-minutes）：

  • 2025-04-23: ohki-shingo, tanenobu がメンテナに
  • 2025-05-07: tokoroten がメンテナに
  • 2025-05-14: ウタコさん（Brand Compass）がメンテナに
  • 2025-06-18: kuboon が website 側書き込み権限

High Priority Issues

毎週の会で「既存 Issues のうち high priority にすべきものは？」を確認する運用（議事メモのテンプレ）。継続的に追求する 4 つ：

  1. Brand Compass に沿った開発
  2. High priority Issues の消化
  3. 情報発信と事例の積み上げ
  4. 運用ポリシーの改善

新規流入者の受け皿

書籍などをきっかけに新規流入が増えても、最初の 1 回で詰まらず、どこから貢献すればよいか分かる状態 を作る必要がある。
そのための開発計画整理は book-release-development-plan-2026-09 を参照。

コントリビュータ導線として特に重要なのは：

  • 最短の setup 手順が 1 本に絞られていること
  • current / deprecated / experimental の境界が docs 上で明示されていること
  • 初回貢献向けの小さい課題が見つけやすいこと
  • issue / PR / wiki の読み方が最低限共有されていること

Open Questions

  • AI 生成 PR（Devin / Copilot Agent）のレビュー責任範囲

Updates

  • 2026-05-17: 初回作成
  • 2026-05-17: open PR を gh pr list で観測する前提と、2026-05-17 時点の主要 open PR を追記
  • 2026-05-18: review fix を push する前に PR head branch の remote 実体を確認する運用メモを追記
  • 2026-05-18: nishio 以外の人間 authored open PR が stale 化している snapshot への参照を追記
  • 2026-05-18: head 更新後に approval が剥がれて merge block される場合があることと、Codex 署名の運用メモを追記
  • 2026-05-18: REVIEW_REQUIRED のままでも admin merge が通る場合があることを追記
  • 2026-05-18: merge 理由コメント → approve → 通常 merge → admin merge fallback の順を追記
  • 2026-05-18: 書籍流入を見込んだ「新規流入者の受け皿」観点を追記
  • 2026-05-18: draft PR は merge せず、ready for review にしてから merge 判断へ進む運用メモを追記
  • 2026-05-20: usage-modes に合わせ、PR を読む前に Web UI / CLI / analysis-core / 共通基盤 を判定する入口を追記
  • 2026-05-21: reviewer request や approval 催促は AI が独断で行わず、人間の明示指示でのみ進める運用メモを追記

グラフビュー

バックリンク