updating-internal-docs

Name: updating-internal-docs
Author: streamlit

github.com/streamlit開発46.2k77 回インストール今日更新

リポジトリ

updating-internal-docs について

現在のコードベースと照らして内部ドキュメントを確認し、古い情報、誤り、欠落、矛盾を見つけるスキルです。修正案を出す前に、検証と報告を行う手順を示します。

主な機能

01ドキュメントのずれと問題種別の特定
02パス、コマンド、依存関係、リンクの確認
03機能変更後のStreamlit同梱スキルの確認
04優先度別の指摘事項整理
05修正前の承認確認

活用シーン

01大規模なコード変更後のドキュメント確認
02makeターゲットや依存関係変更時の説明確認
03Streamlit機能変更に伴うスキル更新の要否判断
04レビュー用の優先度付き指摘事項の作成

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/streamlit/streamlit --skill updating-internal-docs

インストール後、Claude Code で/updating-internal-docsを入力して読み込まれたか確認します。

詳細

内部ドキュメントの更新

内部ドキュメントのファイルを実際のコードベースの状態と照らし合わせて確認し、古くなった情報、誤った情報、欠落している情報の修正を提案します。

使用するタイミング

コードベースに大きな変更があった後（新機能、リファクタリング、ツールの更新）
ドキュメントの乖離が疑われる場合
make ターゲット、フォルダー構造、依存関係、スキル、ワークフローを更新した後
PR が Streamlit の機能を追加または変更する場合 — バンドルされたスキル（lib/streamlit/.agents/skills/）の更新が必要かどうかを確認してください

確認すべき主要ファイル

優先ファイル（コードベース固有の指示が含まれている可能性が最も高いもの）：

**/AGENTS.md - AI エージェント向けの指示
**/README.md - パッケージ／ディレクトリのドキュメント
.claude/skills/*/SKILL.md - Streamlit ライブラリ開発向けのスキル定義
.claude/agents/*.md - サブエージェントの定義
wiki/**/*.md - 開発者向け wiki
CONTRIBUTING.md - コントリビューターガイド
lib/streamlit/.agents/skills/AGENTS.md - バンドルされたスキルの作成手順
lib/streamlit/.agents/skills/*/SKILL.md - Streamlit アプリ開発向けのバンドルされたスキル（ライブラリに同梱されて配布されます）
lib/streamlit/.agents/skills/*/references/*.md - バンドルされたスキルのリファレンスドキュメント

スキップするファイル（同期されたコピーであり、別途更新されます）：

.github/copilot-instructions.md
.github/instructions/*.md
.cursor/rules/*.mdc
.claude/agents/reviewing-local-changes.md の ## Review Checklist 以降（scripts/assets/code-review-instructions.md から生成されます）

ソースの AGENTS.md または scripts/assets/code-review-instructions.md を編集した場合は、uv run python scripts/generate_agent_rules.py を実行して、生成されたコピーが同期された状態を保つようにしてください。

検証チェックリスト

バンドルされたスキルと機能の変更

PR が Streamlit の機能を追加または変更する場合（新しいウィジェット、API の変更、非推奨化、新しい機能）、バンドルされたスキルの更新が必要かどうかを確認してください：

バンドルされたスキルを編集する前に lib/streamlit/.agents/skills/AGENTS.md を読んでください。どの機能に目立つ形でガイダンスを与えるか、またリファレンス、例、ルーティング、公開 API の概要をどのように更新するかが定められています。
lib/streamlit/.agents/skills/developing-with-streamlit/references/ 内のリファレンスドキュメント — 新しい機能や API の変更を記載するために、該当する既存のリファレンスを更新してください

定期的なレビューでは、最近マージされた PR をドキュメントの乖離の手がかりとして扱ってください。それらの差分を調査し、ドキュメントを更新する前に現在のコードを検証してください。マージされたこと自体がバンドルされたスキルの更新を必要とするわけではありません。lib/streamlit/.agents/skills/AGENTS.md の目立たせ方と範囲に関するルールを適用してください。

バンドルされたスキルの更新の一般的なきっかけ：

新しい st.* コマンドまたはウィジェット
既存のコマンドのパラメーター変更
非推奨となった API やパターン（警告を追加し、古い例を削除する）
新しいレイアウトやテーマの機能
パフォーマンスに関連する変更（キャッシュ、フラグメント）

簡単な検証コマンド

# Check path exists: test -e path && echo ok || echo missing
# Check URL reachable: curl -sI -o /dev/null -w "%{http_code}" <url>

ツールのバージョンの参照元

ツール	設定ファイル
TypeScript, React, Vite, Vitest, ESLint, oxfmt, Emotion	`frontend/package.json`
Yarn	`frontend/package.json`（`packageManager` フィールド）
Python, Ruff, mypy, pytest	`pyproject.toml`
Node.js	`.nvmrc`

Issue の種類

種類	説明
OUTDATED	情報がもはや正確でない（古い make ターゲット、名前が変更されたファイル）
INCORRECT	事実として誤っている（誤ったパス、無効なコマンド）
VERSION_MISMATCH	記載されたバージョンが実際と異なる
MISSING	重要な情報が記載されていない。lint、format、type-check、Knip、または CI によってすでに強制されている規約は指摘しないでください。
REDUNDANT	lint、format、type-check、Knip、または CI によってすでに強制されている規約を繰り返している
BROKEN_LINK	存在しないリソースへのリンク
INCONSISTENT	他のドキュメントと矛盾している

ワークフロー

列挙: すべての Markdown ドキュメントファイルを検索します
検証: 記載されたコマンド、パス、例をコードベースと照合します
報告: 優先度ごとにグループ化した検出結果を提示します
修正: ユーザーの承認後に変更を適用します

検出結果の提示

すべての Issue をリストアップし、ユーザーにどれを修正するかを選んでもらいます:

Documentation Review: {SCOPE}
═══════════════════════════════════════════════════════════════

Found {N} issues across {M} files:

1. [OUTDATED] AGENTS.md:42
   Current:  `make python-check`
   Actual:   Command renamed to `make python-lint`

2. [INCORRECT] wiki/testing.md:15
   Current:  Tests in `lib/tests/unit/`
   Actual:   Path is `lib/tests/streamlit/`

3. [BROKEN_LINK] CONTRIBUTING.md:88
   Current:  Link to `./docs/setup.md`
   Actual:   File does not exist

4. [REDUNDANT] frontend/AGENTS.md:20
   Current:  Documents a specific oxlint/eslint/ruff rule (e.g. type-only imports)
   Actual:   Already enforced by lint/CI; omit from docs

Which issues should I fix?
Recommended: "all"
Options: "1" | "1,2,3" | "all" | "skip 3"

ルール

提案の前に検証する: 修正を提案する前に、必ずコードベースを確認してください
最小限の変更: 実際に誤っている箇所のみを変更してください
すべてのドキュメントを選択的かつ簡潔に保つ: コードベースのあらゆる詳細を記載する必要はありません。開発者の判断、正しい使用方法、メンテナンス、または起こりやすいミスの防止に関連する場合にのみ情報を追加してください。単に網羅性のために些細な詳細でドキュメントを膨らませないでください。
CI や lint によってすでに強制されている規約を記載しない: フォーマッター、リンター（ruff、oxlint、eslint）、型チェッカー、Knip、その他の CI チェックがすでに規約に違反して失敗する、または自動修正する場合、それを追加せず、すでに記載されている場合は削除してください。規約を冗長とみなす前に、その名前のルールが存在し有効になっていることを確認してください。エージェントと開発者はどのみちツールのエラーを目にします。ツールのメッセージでは説明されない判断事項、例外、および「代わりに何を使うか」のみを記載してください。それらのツールを実行する方法（make ターゲット、いつ使うか）は引き続き有用です。
耐久性のある高レベルの説明を優先する: make コマンドとワークフローは、その目的、トリガー、いつ使うかという観点で簡潔に説明してください。正しい使用やメンテナンスに重要でない限り、個々の実装手順、オプション、仕組みを記載することは避けてください。
コマンドをテストする: 記載する前にコマンドを実行してください
スタイルを一貫させる: 既存のドキュメントスタイルに合わせてください

レビュー完了後

すべての検出結果をユーザーに提示します
変更を行う前に承認を得ます
修正を段階的に適用します
/checking-changes を実行して検証します

サマリーの例:

Fixed 3 of 4 issues:

- #1 [OUTDATED]: Updated make command in AGENTS.md
- #2 [INCORRECT]: Fixed test path in wiki/testing.md
- #3 [BROKEN_LINK]: Removed dead link in CONTRIBUTING.md
- #4 [INCONSISTENT]: Skipped - requires manual verification

Files modified:
  AGENTS.md         |  2 +-
  wiki/testing.md   |  4 ++--
  CONTRIBUTING.md   |  1 -

Markdown 対応

ログインしてコメント

基本情報

作者: streamlit
リポジトリ: streamlit/streamlit
カテゴリ: 開発
インストール数: 77
GitHub スター: 46,169

問題を報告