sharing-pr-agent-artifacts

PR エージェントの成果物の共有

中間ファイル（実装計画、仕様、学び、調査、アーキテクチャ図）を streamlit.wiki にアップロードし、PR の説明やコメントからリンクできるようにします。これは、レビュアーにとって有用だがメインリポジトリに含めるべきではない、エージェントが生成した成果物に使用します。

重要: wiki リポジトリはデフォルトブランチとして master を使用します。常に master にプッシュし、他のブランチは決して作成しないでください。

wiki のガイドラインに従ってください: wiki リポジトリをクローン/更新した後、何をアップロードし、ファイルをどのように整理するかについての正式なルールとして agent-wiki/AGENTS.md を読み、従ってください。

公開 URL のパターン:

https://issues.streamlit.app/agent_wiki_explorer?file=<relative-path>

例: https://issues.streamlit.app/agent_wiki_explorer?file=pull-requests/12345/implementation-plan.md

前提条件

• 現在のブランチに対して PR が存在している必要があります

ワークフロー

1. PR 番号を取得する

gh pr view --json number --jq '.number'

PR が存在しない場合は、停止してユーザーに知らせてください。

2. wiki リポジトリをセットアップする

wiki がすでにクローンされているか確認します:

if [ -d "agent-wiki/.git" ]; then
  # Use subshell to avoid directory navigation issues if pull fails
  (cd agent-wiki && git checkout master && git pull origin master)
else
  git clone https://github.com/streamlit/streamlit.wiki.git agent-wiki
fi

3. PR ディレクトリを作成する

mkdir -p agent-wiki/pull-requests/<pr-number>

4. ファイルを検出してコピーする

一般的な場所（まずここを確認してください）:

• work-tmp/ — 一時的な作業ファイル、ドラフト、調査ノート
• specs/ — この PR のために作成された、追跡されていない製品/技術仕様

含めるもの:

• 仕様、計画、設計ドキュメント（.md）
• 実装ノートと決定事項
• アーキテクチャ図（.png、.svg）
• 調査結果と探索

常に除外するもの:

Warning: wiki は公開リポジトリです。機密情報、社内のセンシティブな議論、または公開して見えるべきでないものは決してアップロードしないでください。Streamlit はオープンソースであるため、ほとんどすべての技術および製品関連の計画ドキュメントは公開しても問題ありません。

• メインリポジトリですでに追跡されているファイル（確認には git ls-files を使用）
• 認証情報、シークレット、トークン、API キー（.env、*credentials*、*secret*、*token*、*api_key*）
• 機密情報または社内専用の情報
• テスト関連の成果物
• デバッグログと一時出力
• ビルド成果物
• 大きなバイナリファイル（>10MB）
• IDE/エディタのファイル
• 現在の PR に関係のないファイル

選択したファイルをコピーします:

cp <file> agent-wiki/pull-requests/<pr-number>/

5. コミットしてプッシュする

# Use subshell to avoid directory navigation issues
(
  cd agent-wiki
  git checkout master
  git add pull-requests/
  git commit -m "Add artifacts for PR #<pr-number>"
  git pull --rebase origin master
  git push origin master
)

競合によりプッシュが失敗した場合:

1. git pull --rebase origin master を実行する
2. 競合を手動で解決する
3. git rebase --continue を実行する
4. もう一度プッシュする

決して --force を使用しないでください。

6. PR にコメントする

新しいファイルが追加された場合は、要約コメントを PR に投稿します:

gh pr comment <pr-number> --body "$(cat <<'EOF'
### Added Agent Docs

- [implementation-plan.md](https://issues.streamlit.app/agent_wiki_explorer?file=pull-requests/<pr-number>/implementation-plan.md): Main technical implementation plan
- [exploration.md](https://issues.streamlit.app/agent_wiki_explorer?file=pull-requests/<pr-number>/exploration.md): Initial research and design exploration
EOF
)"

レビュアーに関連するトップレベルのドキュメントのみを含めてください。それらのドキュメントに埋め込まれたアセット（例: 画像）は、個別のエントリを必要としません。

PR に依存しない参照ファイル

単一の PR を超えて有用なドキュメント（深掘り、アーキテクチャの探索、調査結果）には、pull-requests/ の代わりに references/ ディレクトリを使用してください。

references をいつ使用するか

• 特定の変更に紐づかないコードベースの探索
• 将来の作業に有用なアーキテクチャの深掘り
• 複数の機能に影響を与える調査結果
• より広い適用範囲を持つ決定ログ

ワークフロー

# Create file with date prefix
mkdir -p agent-wiki/references
cp <file> agent-wiki/references/YYYY-MM-DD-<description>.md

例: 2024-03-15-widget-state-deep-dive.md

PR 成果物と同じコミット/プッシュのワークフロー（ステップ 5）を使用し、git add コマンドとコミットメッセージの両方で pull-requests/ を references/ に置き換えてください（例: "Add reference: YYYY-MM-DD-<description>"）。

公開 URL: https://issues.streamlit.app/agent_wiki_explorer?file=references/YYYY-MM-DD-<description>.md

注意事項

• agent-wiki/ ディレクトリは gitignore されており、セッションをまたいで保持されます
• 常に master にプッシュしてください — フィーチャーブランチを作成したり、--force を使用したりしないでください
• これは公開リポジトリです — 機密情報を決してプッシュしないでください
• 現在の PR に直接関連するファイル、または一般的な参照資料のみをアップロードしてください