cookbook-audit

Cookbook 監査

手順

style_guide.md のガイドラインとルーブリックを使用して、依頼された Cookbook ノートブックをレビューします。スコアリングガイドラインに基づくスコアと、Cookbook を改善するための推奨事項を提供します。

スタイルガイドには、以下の詳細なテンプレートと例が含まれています。

• 終端学習目標（TLO）と実現可能な学習目標（ELO）を備えた、問題に焦点を当てた導入
• 前提条件とセットアップのパターン
• コアコンテンツの構造
• 学習目標に紐づく結論

重要: 監査を実施する前に、必ず最初に style_guide.md を読んでください。スタイルガイドには、参照すべき標準的なテンプレートと良い例・悪い例が含まれています。

ワークフロー

包括的な監査のために、以下の手順に従ってください。

1. スタイルガイドを読む: まず style_guide.md を確認し、現在のベストプラクティスを理解します
2. ノートブックを特定する: パスが指定されていない場合はユーザーに尋ねます
3. 自動チェックを実行する: python3 validate_notebook.py <path> を使用して技術的な問題を検出し、markdown を生成します
   • スクリプトは detect-secrets を自動的に実行し、ハードコードされた API キーや認証情報をスキャンします
   • scripts/detect-secrets/plugins.py で定義されたカスタムパターンを使用します
   • scripts/detect-secrets/.secrets.baseline のベースラインと照合します
4. markdown 出力をレビューする: スクリプトはレビューを容易にするために tmp/ フォルダーに markdown ファイルを生成します（生の .ipynb と比べてコンテキストを節約できます）
   • tmp/ フォルダーは gitignore されており、レビュー成果物がコミットされるのを防ぎます
   • markdown にはコードセルが含まれますが、よりクリーンなレビューのために出力は除外されます
5. 手動レビュー: markdown 版を読み通し、スタイルガイドとルーブリックに照らして評価します
6. 各次元を採点する: スコアリングガイドラインを客観的に適用します
7. レポートを生成する: 以下の監査レポート形式に従います
8. 具体的な例を提示する: スタイルガイドのテンプレートを使用して、行参照付きの具体的な改善案を示します

監査レポートの形式

以下の構造を使用して監査を提示してください。

エグゼクティブサマリー

• 総合スコア: X/20
• 主な強み（2〜3 個の箇条書き）
• 重大な問題（2〜3 個の箇条書き）

詳細な採点

1. ナラティブの品質: X/5

[具体的な例を挙げた簡潔な根拠]

2. コードの品質: X/5

[具体的な例を挙げた簡潔な根拠]

3. 技術的な正確性: X/5

[具体的な例を挙げた簡潔な根拠]

4. 実行可能性と理解: X/5

[具体的な例を挙げた簡潔な根拠]

具体的な推奨事項

[特定のセクションへの参照を含む、優先順位付けされた実行可能な改善リスト]

例と提案

[ノートブックからの具体的な抜粋と、改善のための具体的な提案を示します]

クイックリファレンスチェックリスト

網羅的にカバーできているか、次の項目で確認してください。

はじめに（style_guide.md セクション 1 を参照）

• 解決する課題を提示する（1～2 文）
• それが重要な理由を説明する（1～2 文）
• 学習目標を箇条書きで示す（TLO／ELO を 2～4 項目）
• 構築する仕組みではなく、提供する価値に焦点を当てる
• 任意：より広範な用途に触れる（1 文）

前提条件とセットアップ（style_guide.md セクション 2 を参照）

• 必要な知識を明確に示す
• 必要なツールを列挙する（Python のバージョン、API キーなど）
• 該当する場合は、推奨される事前知識に触れる
• 出力を抑制するため、pip install に %%capture を使用する
• os.environ ではなく dotenv.load_dotenv() を使用する
• MODEL 定数を先頭で定義する
• 関連するインストールを 1 つのコマンドにまとめる

構成と整理

• セクションが論理的な順序で構成されている
• 各セクションで、実演を通して説明する
• コードブロックの前に説明文を置く
• コードブロックの後に学んだ内容をまとめる
• 見出しを使ってセクションを区切る

まとめ（style_guide.md セクション 4 を参照）

• 学習目標との対応を示す
• 達成した内容を要約する
• 学んだことをユーザーの状況に応用する方法を提案する
• 次のステップや関連リソースを案内する

コードの品質

• すべてのコードブロックの前に説明文がある
• API キーをハードコードしていない（detect-secrets による自動チェック）
• 意味のある変数名を使用している
• コメントでは「何を」ではなく「なぜ」を説明する
• 言語のベストプラクティスに従っている
• ノートブックの先頭でモデル名を定数として定義している

出力の管理

• %%capture で pip install のログを抑制している
• 詳細すぎるデバッグ出力がない
• 関連性のある API レスポンスを表示する
• エラー処理を実演する場合に限り、スタックトレースを表示する

コンテンツの品質

• アプローチが有効な理由を説明する
• このアプローチを使う場面について説明する
• 制限事項や考慮点に触れる
• 応用可能な知識を提供する
• モデルを適切に選択する

技術要件

• （API キーを除き）変更なしで実行できる
• 非推奨ではない API パターンを使用している
• 各ファミリーの最新モデル（claude-opus-5-5、claude-sonnet-5-5、claude-fable-5-1、claude-haiku-4-5）を使用している。提供が継続されているものの後継モデルがある ID（例：claude-opus-5、claude-sonnet-5）は、意図的に固定していない限り警告対象です。提供が終了した ID（例：claude-3-*）はブロッキング対象です
• 日付のないモデルエイリアスを使用している（日付付き ID（例：claude-sonnet-4-5-20250929）は使用しない）
• ノートブックの先頭でモデル名を定数として定義している
• 依存関係の指定を含めている
• 主要カテゴリに割り当てている
• 関連するタグを付けている

コンテンツの基本方針：実践と理解

Cookbook は主に実践を重視しつつ、Diataxis フレームワークに基づき、理解を戦略的に取り入れます。

基本原則：

• 実践を重視する：動作するコードを使って、具体的なタスクの達成方法を示す
• 課題を起点にする：仕組みではなく、解決する課題と提供する価値を最初に示す
• 作り手の視点に立つ：ユーザーの視点から、現実の課題を解決するように書く
• 主体性を育む：方法だけでなく、アプローチが有効な理由をユーザーが理解できるようにする
• 応用可能な知識を提供する：具体例にとどまらず、ほかの場面にも適用できるパターンや原則を教える
• 批判的思考を促す：出力を吟味し、制限事項を認識し、情報に基づいて選択できるよう促す
• 学習の約束を明示する：学習目標を最初に示し、まとめでそれらに立ち返る

優れた Cookbook とは

優れた Cookbook は、今日の課題を解決する手助けをするだけではありません。解決策の背後にある原則を理解し、アプローチをいつ、どのように応用すべきかを見極められるようにします。ユーザーは AI システムの設計について、より情報に基づいた判断を下せるようになり、モデルの出力を評価する力を養い、将来の AI システムにも応用できるスキルを身につけられます。

Cookbook ではないもの

Cookbook は純粋なチュートリアルではありません。ユーザーが基本的な技術スキルと API の知識を持っていることを前提としています。Cookbook では前提条件を明確に記載し、トピックについてさらに学ぶために Academy へ誘導します。 包括的な説明ではありません。Transformer アーキテクチャや確率論を教えるものではありません。ユーザーが今直面している問題を解決するために Cookbook を利用していることを理解する必要があります。ユーザーは忙しく、学習中または構築中であり、学んだことを目の前の課題の解決にすぐ使いたいと考えています。 Cookbook はリファレンスドキュメントではありません。すべてのパラメータを網羅的に文書化するのではなく、必要に応じてドキュメント内の適切なリソースへリンクします。 Cookbook は単なる Tips や小技ではありません。現在のモデル世代にしか通用しない「ハック」を教えることはしません。過度な期待を抱かせて実際には応えられない、ということはしません。 Cookbook は本番環境向けのコードではありません。本番環境のパターンではなく、ユースケースと機能を紹介します。過剰なエラーハンドリングは必要ありません。

スタイルガイドライン

声とトーン

• 教育的で、主体性を育む
• プロフェッショナルでありながら親しみやすい
• ユーザーの知性と時間を尊重する
• 二人称（「あなた」）または一人称複数（「私たち」）のいずれか - ノートブック内で一貫させる

文章の品質

• 明確で簡潔な説明
• 能動態を優先
• 短い段落（3〜5 文）
• 定義なしの専門用語を避ける
• 見出しを使ってセクションを区切る

コードの提示

• 必ず説明してから提示する: すべてのコードブロックの前には説明文を置く
• 実行後に説明する: コードブロックの実行後に得られた学びを含める
• コメントは why を説明し、what は説明しない: 意味のある変数名を使う
• 定数を使う: 先頭で MODEL を定数として定義する
• 良い習慣: os.environ ではなく dotenv.load_dotenv() を使う

出力の扱い

不要な出力は %%capture で除去する:

• pip install のログ（これらは常に抑制する）
• 冗長なデバッグ出力
• 長いスタックトレース（エラーハンドリングの実演を除く）

関連する出力は表示する:

• 機能を示す API レスポンス
• 成功した実行の例

構造上の要件

詳細なテンプレートと例については style_guide.md を参照してください

1. はじめに（必須）

必ず含めるもの:

• 問題への引き込み（1〜2 文）: 私たちはどのような問題を解決するのか？
• なぜ重要か（1〜2 文）: これがなぜ重要なのか？
• 学習目標（2〜4 個の箇条書き）: 「この Cookbook を終えるころには、次のことができるようになります…」
  • 動作動詞を使う（Build、Implement、Deploy など）
  • 具体的な能力を示す
  • 文脈や制約を含める
• 任意: より広い応用（1 文）

❌ 避ける: 仕組みから始める（「私たちはリサーチエージェントを構築します…」） ✅ 行う: 問題や価値から始める（「あなたのチームは CI の失敗のトリアージに何時間も費やしています…」）

2. 前提条件とセットアップ（必須）

必ず含めるもの:

• 必要な知識: 求められる技術スキル
• 必要なツール: Python のバージョン、リンク付きの API キー
• 推奨: 役立つ任意の背景知識
• セットアップ: 説明付きの手順
  • pip install には %%capture を使う
  • os.environ ではなく dotenv.load_dotenv() を使う
  • 先頭で MODEL 定数を定義する

3. メインコンテンツ（必須）

論理的なステップまたはフェーズごとに整理し、それぞれに以下を含めます:

• 明確なセクション見出し
• コードブロックの前の説明文（これから何をするのか）
• コード例
• コードブロックの後の説明文（何を学んだのか）
• 期待される出力（該当する場合）
• 任意: 理解を助ける補足（なぜ機能するのか、いつ使うのか、制限事項）

4. まとめ (推奨)

必ず含めるもの:

• 振り返り: 学習目標に立ち返る
• 達成したこと: 要点のまとめ
• 応用の指針: 学んだことをユーザーの状況にどう活かすか
• 次のステップ: pursuing すべき関連リソースやアイデア

❌ 避ける: 一般的なまとめ (「SDK がどのように実現するかを示しました…」) ✅ 行う: 実行可能な指針 (「これを X に適用することを検討してください… 次に、Y を試してみてください…」)

任意のセクション

• 仕組み: 背後にあるメカニズムの簡単な説明
• 使うべき場面: 適切なユースケースとコンテキスト
• 制限と考慮事項: 注意点、失敗モード、制約
• トラブルシューティング: よくある問題と解決策
• バリエーション: 代替アプローチや拡張
• パフォーマンスに関する注意: 最適化の考慮事項
• 参考文献: 関連ドキュメント、論文、またはより詳しい解説へのリンク

指摘すべきよくあるアンチパターン

詳細な良い例・悪い例については style_guide.md を参照してください。以下の問題に注意してください:

はじめにのアンチパターン

❌ 仕組みから始める: 「Claude SDK を使ってリサーチエージェントを構築します…」 ❌ 機能の羅列: SDK のメソッドやツールの機能を列挙する ❌ 曖昧な学習目標: 「エージェントについて学ぶ」または「API を理解する」 ✅ 問題を起点としたフレーミングと、具体的で実行可能な学習目標

セットアップのアンチパターン

❌ %%capture なしの雑多な pip install 出力 ❌ 複数の別々の pip install コマンド ❌ dotenv の代わりに os.environ["API_KEY"] = "your_key" を使用する ❌ MODEL 定数を使わず、モデル名を全体にハードコードする ✅ インストールをグループ化し、dotenv と定数を使ったクリーンなセットアップ

コード提示のアンチパターン

❌ 前に説明テキストのないコードブロック ❌ コードを実行した後に、何を学んだかの説明がない ❌ コードが「何」をするかを説明するコメント (コードは自己文書化されるべき) ❌ 明らかなコードを過度に説明する ✅ コードの前に文脈、コードの後に洞察、コメントは「なぜ」を説明する

まとめのアンチパターン

❌ 一般的なまとめ: 「SDK がどのように実現するかを示しました…」 ❌ 指針なしでノートブックが行ったことをただ繰り返す ❌ 示された学習目標に立ち返らない ✅ 学んだことをユーザーの具体的な状況に適用するための実行可能な指針