テンプレートをCopierで効率的に管理・運用する
X-tech推進本部 齋藤はじめに
一定の品質を保ちながら開発のさまざまな作業を効率よく進めるために、社内でテンプレートを用意しておくことはよくあると思います。
ミツエーリンクスでも、よく使う構造をHTMLとCSSを組み合わせたパターンとして用意したり、AstroやNext.jsを使った構成を用意したりしています。
ただ、テンプレートは用意して終わりではありません。使い始めてからも、更新を届けたり取り込んだりといった運用が続きます。
この記事では「Copier」を使ったテンプレートの効率的な管理・運用方法を紹介します。
テンプレート運用の課題
テンプレートをGitHubで管理しているなら、テンプレートからリポジトリを作る方法や、フォークを使うのが一般的だと思います。 どちらも、テンプレートのリポジトリをもとに新しいリポジトリを手軽に作れます。
ただ、これらのやり方にはできないこともあります。
テンプレートを組み合わせたり、中身を変えたりできない
テンプレートリポジトリもフォークも、リポジトリ単位でコピーする仕組みです。
そのため、テンプレートはリポジトリ1つ分を丸ごと用意する必要があります。
AIエージェントの設定ファイルのように、必要な部分だけをテンプレートにして、既存のリポジトリに追加することはできません。
複数のテンプレートを組み合わせて、1つのリポジトリを作ることもできません。
また、コピーするときにプロジェクト名などを指定して、中身を変えることもできません。
コピーしたあとに、各環境に合わせて手作業で書き換えることになります。
更新の反映状況を揃えづらい
テンプレートリポジトリから作ったリポジトリは、テンプレートとの間で履歴がつながっていません。そのため、テンプレートリポジトリの作り方にあるとおり、更新をGitでマージして取り込むことはできません。
テンプレートの新しいバージョンを出したら、何が変わったのか・どう反映すればよいのかを、アナウンスなどで逐一説明する必要があります。
使う人はその説明を見ながら、各環境に手作業で反映します。脆弱性への対応のような急ぎの修正でも同じです。
さらに、テンプレートは使っていくうちに環境ごとの要件が加わり、元の内容との差が広がっていきます。
差が広がるほど、更新を手作業で取り込むのは大変になります。
その結果、同じテンプレートから作った環境でも、どこまで更新が反映されているのかがばらばらになり、把握もしづらくなります。
フォークなら元のリポジトリの履歴を引き継ぐので、フォークを同期して更新を取り込むことができます。
Copierとは
表題にもある「Copier」は、テンプレートをコマンドひとつでコピーするためのツールです。用意しておいたテンプレートを、いくつかの質問に答えるだけで好きな場所にコピーできます。
テンプレートにはどんなファイルでも含めることができ、ファイルの中身をユーザーが入力した任意の値に書き換えられます。また、テンプレート本体が更新されたときに、その更新をコピー先に取り込むための仕組みもあります。
環境準備
必要なツールは、Copierのインストール手順に従って用意します。
すでにmiseを使っているなら、それらをあらかじめインストールしておかなくても、mise exec(mise x)でCopierを実行できます。
--のあとに、実行したいCopierのコマンドを書きます。
mise x python@latest uv@latest copier@latest -- copier --version
テンプレートを作る
Copierのテンプレートは、設定ファイルのcopier.ymlと、生成したいファイルの一式です。
例えば次のような構造の場合、my_templateディレクトリがテンプレートになります。
my_template/
├ copier.yml
├ {{_copier_conf.answers_file}}.jinja
├ mise.toml
├ package.json.jinja
└ src/
└ ...
質問を定義する(copier.yml)
Copierは、テンプレートをコピーするときに、ユーザーに対話形式でいくつか質問をします。この質問は、設定ファイルcopier.ymlにあらかじめ定義します。
そこで回答した内容は、プロジェクト名などとしてファイルの中に埋め込まれます。
typeで回答の型を、helpで質問の文を指定します。下記の例は、プロジェクト名を質問する設定です。
project_name:
type: str
help: プロジェクト名を入力してください
Jinjaの記法で回答を埋め込む
テンプレートのファイルは、基本的にはそのままコピーされます。例えばmise.tomlはmise.tomlとしてコピーされます。
一方、.jinja拡張子のファイルだけは、質問の回答を流し込んでからコピーされます。コピー後はファイル名から.jinja拡張子は外れます。
Jinjaは、Pythonで書かれたテンプレートエンジンです。ファイルの中に{{ 変数名 }}のようなプレースホルダーを書いておくと、その部分を変数の値に置き換えて出力できます。
Copierはこの仕組みを使って、質問の回答をファイルに埋め込みます。
下記の例では、package.json.jinjaは、質問で回答したプロジェクト名が{{ project_name }}に入り、package.jsonとしてコピーされます。
{
"name": "{{ project_name }}",
"version": "0.1.0",
"private": true
}
ファイル名やディレクトリ名にもJinjaの記法を使えます。パスへの書き方はテンプレートの作り方にまとまっています。
Copierでできること
コマンドひとつでテンプレートをコピーできる
テンプレートを複製して使い始められる状態にするまでの作業が、copier copyコマンドひとつで済みます。
テンプレートの場所と、コピー先のディレクトリを設定します。
copier copy https://github.com/mitsue-links/my_template.git my-site
※ テンプレートの場所には、ローカルのパス・GitリポジトリのURLも指定できます
copier.ymlで定義した質問に答えると、次のようにファイルがコピーされます。
Copying from template version 1.0.0
create mise.toml
create package.json
create src
create src\index.html
create .copier-answers.yml
テンプレートの更新を取り込める
テンプレートを更新したら、そのテンプレートのコピー先でもcopier updateで更新を取り込めます。
テンプレートを1か所更新するだけで、同一テンプレートからコピーされたものすべてに同じ更新を届けられます。
更新を取り込むために必要なもの
テンプレートに{{_copier_conf.answers_file}}.jinjaというファイルを作り、次の内容を記述しておきます。
# Changes here will be overwritten by Copier
{{ _copier_answers|to_nice_yaml -}}
コピー時に、このファイルから、テンプレートの場所・バージョン・質問への回答を記録した.copier-answers.ymlが生成されます。
例えば、次のような内容になります。
# Changes here will be overwritten by Copier
_commit: v1.0.0
_src_path: https://github.com/example/my_template.git
project_name: my-site
_src_pathがテンプレートの場所、_commitがテンプレートのバージョン、project_nameが質問への回答です。
copier updateはこの記録をもとに更新を取り込むので、テンプレートには必ずこのファイルを用意しておきます。
また、更新を取り込むコピー先はGitで管理しておく必要があります。
テンプレートのバージョンは、テンプレートのリポジトリのGitタグで決まります。
Gitタグがある場合は、最新のGitタグのバージョンに更新され、.copier-answers.ymlの_commitにはそのGitタグ(例:v1.1.0)が記録されます。
Gitタグがない場合は、テンプレートの最新のコミットに更新され、_commitにはコミットのハッシュが記録されます。
どちらでも更新は取り込めますが、Gitタグを付けておくと、どのバージョンまで取り込んだのかが分かりやすくなります。
コンフリクトが起きたとき
コピー先とテンプレートの両方で同じ場所を変更していた場合は、コンフリクトになります。
Gitのマージと同じように、ファイルにマーカーが入るので、手作業で解決します。
例えば、コピー先でpackage.jsonに"license": "MIT"を追加していたところに、テンプレートでも同じ場所に"license": "UNLICENSED"を追加すると、次のようにコンフリクトになります。
before updating側がコピー先の内容、after updating側がテンプレートの新しい内容です。
{
"name": "my-site",
<<<<<<< before updating
"license": "MIT",
=======
"license": "UNLICENSED",
>>>>>>> after updating
"version": "0.1.0",
"private": true
}
何をテンプレートに含めるか
Copierのテンプレートには、どんなファイルでも含められます。そのため、Webサイトのひな形だけでなく、次のような用途でも使えます。
AIエージェントの設定ファイル
Claude CodeやCursorのようなAIエージェントは、使う人ごとにカスタマイズする部分も多いです。
一方で、禁止したいコマンドや共有したいスキルのように、チームで揃えたい設定もあります。
AIエージェントには、Claude Codeの管理設定やCursorのチームダッシュボードのように、組織で設定を管理する仕組みも用意されています。ただし、組織向けのプランの契約が前提になっていたり、管理できる範囲がツールごとにまちまちだったりします。
Copierなら、設定ファイルをテンプレートとしてコピーするだけなので、プランの契約は関係ありません。
また、ファイル単位でテンプレートに含められるので、設定ファイルやスキルと、それらが参照するAGENTS.mdのような関連ファイルをセットで届けられます。
ツールやパッケージのバージョン
テンプレートの更新として、ツールやパッケージのバージョンを上げる変更も届けられます。
例えばNode.jsのセキュリティリリースが出たときに、テンプレートのmise.tomlで修正済みのバージョンに上げておけば、各環境ではcopier updateで取り込めます。
パッケージのバージョンも同じように届けられるので、脆弱性への対応や、問題のあるバージョンを避けるといったサプライチェーン攻撃への対応も、テンプレートの更新として取り込めます。
何を更新するかはテンプレートの管理者が判断するので、使う人はその更新を取り込むかどうかだけを決めれば済みます。
Dependabotのような仕組みを使うなら、コピー先ではなくテンプレートのリポジトリで使うのがよいでしょう。
各環境で別々に更新すると、テンプレートとの差が広がり、copier updateでコンフリクトが起きやすくなります。
テンプレートで更新を受けて取り込んでもらえば、更新の元が1つにまとまります。
インフラの設定ファイル
例えば、Cloudflare・GitHubなどのSaaSを使うプロジェクトの場合、それぞれの設定は毎回ダッシュボードから手作業で行うことが多いと思います。
こうした設定の多くは、TerraformやOpenTofuのようなツールでコードとして書けます。
その設定ファイルをテンプレートに含めておけば、コピーするときにインフラの設定もまとめて届けられます。
ツールが対応していない設定は手作業で補う必要がありますが、毎回ダッシュボードで行っていた作業の多くをテンプレートから届けられるようになります。
まとめ
開発で品質を保つうえで、同じものを同じやり方で使い続けられる一貫性は欠かせません。
ところが、テンプレートのコピーや更新の取り込みを人の手で行っていると、どうしても手間がかかり、取り込み漏れや作業の間違いも起こります。
Copierを使えば、テンプレートのコピーも更新の取り込みもコマンドで行えて、どの環境がどこまで更新を取り込んだのかも記録に残ります。
人の手に頼っていた作業を仕組みに任せることで、手間を減らしながら一貫性を保ちやすくなります。