cookiecutter

Cookiecutter テンプレートの作業

cookiecutter.json、hooks/、または {{ cookiecutter.project_slug }}/ のような生成済みプロジェクトディレクトリがあるリポジトリを変更する前に、このスキルを使用してください。

最初の確認

1. 編集前に、リポジトリの指示、README.md、cookiecutter.json、既存のテスト、 フックを読みます。
2. テンプレートのルートと生成されるプロジェクトのルートを特定します。変更は 1 つのレンダリング済みサンプルではなく、テンプレートファイルに加えます。
3. 新しい変数を追加する前に、関連する Cookiecutter 変数と機能フラグを rg で検索します。
4. リポジトリがレンダリング済みプロジェクトをどのように検証しているか確認します。 独自の検証方法を作るより、既存のレンダリングテストやスモークチェックコマンドを優先します。

テンプレートの境界

• cookiecutter.json はユーザー向けインターフェースです。新しいプロンプト、デフォルト値、 派生値、非公開値、選択肢はすべて意図的に設計し、リポジトリでオプションを説明している場所に記載します。
• 生成されるプロジェクトディレクトリ内のファイル名やパス自体に、Jinja が含まれる場合があります。 ファイルの内容とパスの両方をレンダリング対象として扱います。
• リポジトリで現在使われている変数のスタイルに従います。新しい機能フラグに y／n の文字列を使用している場合は、そのスタイルを使い続けます。Cookiecutter のブール値を 使用している場合は、実際の JSON ブール値を使い続けます。
• オプション機能は、有効な場合と無効な場合のどちらでも正常に動作する必要があります。 アプリのファイル、インポート、URL ルート、設定、依存関係、ドキュメント、テスト、 ワークフロー、マイグレーションを、まとめて削除するか条件付きで含めます。
• 生成される出力に、メンテナー固有の名前、ローカルパス、シークレット、単一エージェントを前提とする記述を追加しないでください。

Jinja のルール

• レンダリング後のファイルが、対象言語（Python、JSON、TOML、YAML、 シェル、Markdown、HTML、JavaScript、CSS）として有効であることを確認します。
• JSON、TOML、Python のデータ構造、YAML リスト、パッケージマニフェスト、 GitHub Actions では、条件ブロックの後に余分なカンマが残らないよう注意します。
• 空白制御（{%- ... -%}）は、レンダリング後の構文や書式の改善に役立つ場合にのみ使います。 テンプレートソースだけでなく、レンダリング結果も検証します。
• コードやデータファイルに挿入する文字列は、安全にシリアライズします。すでに使われている場合は、 |tojson など、リポジトリ既存の JSON／Jinja フィルターパターンを優先します。
• 生成される出力でリテラルの Jinja、テンプレート構文、またはエージェントのプレースホルダーを そのまま保持する必要がある場合は、中括弧をエスケープするか、raw ブロックで囲むか、 パスを _copy_without_render に追加します。
• _copy_without_render を指定するとファイルの内容はレンダリングされませんが、パスはレンダリングされます。 ツリー全体をそのままコピーする場合は、ディレクトリと再帰的な glob の両方を指定します。

フック

• Cookiecutter のフックは hooks/ に pre_prompt、pre_gen_project、または post_gen_project のスクリプトとして配置します。リポジトリが意図的に特定プラットフォーム向けでない限り、 クロスプラットフォームのテンプレートでは Python を優先します。
• pre_gen_project と post_gen_project は生成されたプロジェクトのルートから実行され、 レンダリング済みの Cookiecutter 変数を使用できます。
• フックは決定的で、冪等かつ相対パスを基準にしたものにします。ネットワーク呼び出し、シークレット、 対話型プロンプト、マシン固有のパスは避けます。
• フックの終了コードがゼロ以外の場合、生成は停止し、Cookiecutter は生成されたディレクトリを削除します。 無効なユーザー入力は早い段階で失敗させ、クリーンアップは堅牢に行います。
• 任意のファイルやディレクトリ全体を削除するには、生成後のクリーンアップを使います。 ファイル内の小規模で構文を考慮する変更には、インライン Jinja を使います。

テスト

• 明示的なコンテキスト値を指定してテンプレートをレンダリングするテストを追加または更新してください。 変更した各オプションについて、可能な場合は有効時と無効時の両方をテストしてください。
• 存在することだけでなく、存在しないこともアサートしてください。無効にしたオプション機能によって、インポート、依存関係、ルート、ドキュメント、ワークフロー、マイグレーション、プレースホルダーテキストが残らないようにしてください。
• 生成動作、フック、テンプレートの選択、またはコマンドラインに関する前提を変更する場合は、実際の Cookiecutter CLI を使用してください。
• ランタイムの動作を変更する場合は、一時ディレクトリにプロジェクトを生成し、そのプロジェクトでドキュメントに記載されたチェックを実行してください。
• 構文に影響されやすいファイル（JSON、TOML、YAML、Python モジュール、シェルスクリプト、パッケージマニフェスト）を確認してください。

よくある失敗パターン

• Jinja によって、構文的には有効なテンプレートソースが、無効な生成コードにレンダリングされる。
• 無効にしたオプションでファイルは削除されるが、設定、インポート、URL、依存関係、ドキュメント、テスト、マイグレーション、CI 参照が残る。
• 生成されるプロジェクトで使うことを意図したリテラルの {{ ... }} プレースホルダーが、Cookiecutter に処理される。
• フックが、生成されたプロジェクトのルートではなく、テンプレートリポジトリが作業ディレクトリであることを前提としている。
• テストで正常なコンテキストを1つだけレンダリングし、サポート対象の別のオプションの組み合わせを見落とす。
• 生成ファイルにローカルパス、個人名、シークレット、または特定の AI ツールに依存する前提が含まれている。

完了の定義

• テンプレートの変更がテンプレートレベルで行われている。
• 有効時と無効時の関連するオプションの組み合わせで、正常にレンダリングされる。
• 生成された出力に、古いプレースホルダー、構文エラー、孤立したインポート、メンテナー固有のハードコード値がない。
• リポジトリのテンプレートテストスイートが成功する。
• ユーザーや生成されたプロジェクトのコントリビューターに変更を知らせる必要がある場合は、ドキュメントと変更履歴の項目が更新されている。

参考資料

• 公式ドキュメント：https://cookiecutter.readthedocs.io/en/stable/
• 上流リポジトリ：https://github.com/cookiecutter/cookiecutter