前回は、業務で使ってきた帳票デザインソフトの「ちょっとした不便」をきっかけに、自分で帳票作成システム Kasane（重ね） を作り始めた経緯を書きました。
今回は、いよいよ開発に入る…前に、最初にやったことの話です。それは、コードを1行も書かずに「仕様書を書く」ことでした。
業務系のプログラマなら「そりゃ仕様書は書くでしょ」と思うかもしれません。ですが、AI（Claude Code）と一緒に開発する場合、仕様書にはもう一つの重要な役割があることに気づきました。
なぜ最初に仕様書を書いたのか
私が最初に作ったのは、docs/file-format.md という1枚のマークダウンファイルでした。
これは「Kasane のファイル形式」を定義した仕様書です。中身は、こんな問いに答えるものでした。
- 帳票のテンプレートは、どんな形式で保存するのか?
- データはどう渡すのか?
- 「重ね合わせ」をどう表現するのか?
コードを書き始める前に、この仕様書をじっくり作りました。理由は2つあります。
理由1: 設計のブレを防ぐ
帳票作成システムのような「土台」が大事なソフトは、最初の設計が後のすべてを決めます。データ構造を後から変えると、その上に積み上げたコードが全部崩れる。
最初に仕様を固めることの価値は、業務システム開発で何度も痛感してきました。
理由2: AIとの「共通理解の土台」になる
これが今回の発見でした。
Claude Code に「こういうものを作って」と毎回口頭（チャット）で説明していると、少しずつ認識がズレていくことがあります。会話が長くなるほど、最初に決めたことが曖昧になる。
ですが、docs/file-format.md という明文化された仕様書があれば、Claude Code に「この仕様書を読んで実装して」と伝えるだけで済みます。仕様書が、私とAIの間の「正」となる共通の参照点になるのです。
実際、開発のたびに私はこう指示しました。
「docs/file-format.md を読んで、Phase 1 を実装してください」
仕様書を更新したら、また「更新版を読んで」と伝える。これで、何度実装を重ねても設計がブレない。これは AI と開発する上で、想像以上に効きました。
Kasane のファイル形式: 2つのファイルで1つの帳票
では、実際にどんな仕様にしたか。Kasane の帳票は、2つのファイルの組み合わせで表現することにしました。
テンプレート（.kasane）とデータ（.dat）
| ファイル | 役割 | 形式 |
|---|---|---|
.kasane | 帳票のデザイン（レイアウト、罫線、文字の位置） | XML |
.dat | 帳票に流し込むデータ（顧客名、金額など） | INI ライク |
これは業務帳票システムの王道パターンです。「デザイン」と「データ」を分離することで、1つのテンプレートに次々と違うデータを流し込んで、大量の帳票を生成できます。
例えば請求書なら、テンプレートは1つ作っておき、顧客ごとのデータ（.dat）を流し込めば、何百枚もの請求書が出力できる、というわけです。
なぜ XML と INI なのか
ここは設計判断でした。独自のバイナリ形式にする選択肢もありましたが、あえてテキスト形式を選びました。
理由:
- 人間が読める: テキストエディタで開けば中身が分かる
- Git で管理できる: 差分が見える、バージョン管理しやすい
- 手で編集できる: ちょっとした修正ならエディタで直せる
- デバッグしやすい: 何かおかしい時、ファイルを開けば原因が分かる
前回書いた「ある業務ソフトの独自バイナリ形式は中身が読めない」という不満への、私なりの答えです。透明性を最優先しました。
Kasane の中心思想: レイヤー
仕様書を書く中で、一番こだわったのが 「レイヤー」 の設計です。
前回書いた通り、私が最初に困ったのは「条件によって帳票に重ねる図を変える」ことでした。この課題を、後付けの機能ではなく設計の中心に据えることにしました。
レイヤーの考え方
Photoshop を使ったことがある方なら、レイヤーパネルを思い浮かべてください。複数の絵を「層（レイヤー）」として重ね、表示・非表示を切り替えられる、あの仕組みです。
Kasane も同じ発想にしました。帳票を複数のレイヤーで構成し、データ（.dat）の指定によって、どのレイヤーを表示するかを切り替える。
簡単な例で言うと、こんなイメージです。
- ベースレイヤー: 常に表示される帳票の本体（罫線、項目名）
- 「支払済」レイヤー: 条件に応じて重ねる赤いスタンプ
- 「未払い」レイヤー: 別の条件で重ねる青いスタンプ
データ側で「支払済レイヤーを表示」と指定すれば、赤いスタンプ付きの帳票になる。「未払いレイヤー」を指定すれば青いスタンプになる。テンプレートは1つのまま、データの指定だけで見た目が変わるわけです。
「重ね色目」という名前の由来
このレイヤー思想が、プロジェクト名の由来になっています。
日本の伝統に「重ね色目（かさねのいろめ）」という美意識があります。平安時代の装束で、複数の色の布を重ねることで、一つの美しい表現を生み出す文化です。
複数の意匠を重ねて一つの帳票を作る——この思想を込めて、プロジェクトを 「Kasane（重ね）」 と名付けました。
仕様書を「先に」書くことの効用
ここで、業務系プログラマの方に特に伝えたいことがあります。
AI 開発ツール（Claude Code など）を使うと、つい「とりあえず動くものを作って」と指示しがちです。確かに、それでも何か動くものはできます。
ですが、最初に仕様書を書いておくと、AI の出力品質が段違いに上がります。
私の体感では、
- 仕様書なしで「いい感じに作って」→ 毎回少しずつ違うものができる
- 仕様書ありで「この仕様書通りに作って」→ 設計が一貫し、手戻りが激減
これは、人間のチーム開発で「仕様書を共有する」のと全く同じ効果です。AI が相手でも、明文化された共通理解が品質を支えるのです。
仕様書を書く時間は、決して無駄ではありません。むしろ、後の実装フェーズを何倍も速く・正確にする投資でした。
次回予告
仕様が固まったら、いよいよコードを書き始めます。
次回は Phase 1: コアライブラリの実装 の話です。.kasane（XML）と .dat（INI）を読み込んで、メモリ上の帳票データに変換する、Kasane の心臓部を作りました。
ここで一つ、技術的な選択をしました。XML を読むのに、C# 標準の XmlSerializer を使うか、それとも XLinq で手書きパースするか。
Claude Code はある理由で後者を選びました。その判断が、なぜ正しかったのか——次回、詳しく書きます。
それでは、また次回。
