サムネイル画像の生成処理をメインリポジトリから切り離した記録
著者: ClaudeMix Team |
サムネイル画像のリサイズ・WebP変換処理をメインリポジトリから切り離し、Cloudflare R2への外部化によってエッジ環境の制約と画像処理ライブラリの衝突を解消した。
① やったこと
Before: 画像処理(リサイズ・WebP変換)のロジックがブログ本体のリポジトリに同居していた。Node.js前提の画像処理ライブラリと、Cloudflare Workers(エッジ)のランタイム制約が同じpackage.json・同じCLAUDE.mdの中に混在し、AIエージェントへの指示もこの両立を説明する内容が増え続けていた。
After: 画像処理を別リポジトリに分離し、生成した画像はCloudflare R2にアップロードして、ブログ本体はR2の不変URLを参照するだけの構成にした。
// image-repo/processor.ts(分離後、別リポジトリ側)
import sharp from 'sharp';
import { R2Client } from './storage';
export async function processThumbnail(slug: string, inputPath: string) {
const buffer = await sharp(inputPath)
.resize(1200, 630, { fit: 'cover' })
.webp({ quality: 80 })
.toBuffer();
await R2Client.put(`blog/thumbnails/${slug}.webp`, buffer);
}ブログ本体側(メインリポジトリ)には、画像処理に関するコードやライブラリは一切存在しない。
② 設計判断
- 【優先した価値】: メインリポジトリのCLAUDE.md・package.jsonを、エッジランタイムの制約だけに絞ること
- 【犠牲にした価値】: 記事保存から画像生成までを1本のパイプラインで完全自動化する道を捨てた。分離した画像処理リポジトリ側でslugを手動入力して実行する一手間を、意図的な安全装置として残した
③ 技術的負債
- 【解消した負債】: メインリポジトリのCLAUDE.md・package.jsonが、画像処理ライブラリのエッジ環境における制約を説明する必要がなくなった
- 【新たに生まれた負債】: リポジトリが2つに分かれたことで、画像のパス命名規則やスキーマの同期をレビューで人力管理する必要が生まれた。片方だけを変更すると、もう片方が参照するURLの形式と食い違うリスクが残っている
④ 経営翻訳
本店の業務マニュアルに、外部委託している印刷工場の設備仕様まで書き込んでいたため、印刷機を更新するたびに本店側のマニュアルも修正が必要になっていた状況に相当する。印刷工場を別会社として切り出し、本店は完成品を受け取る窓口だけを持つようにすることにした。
この「言わなくていいことを増やす」思想は、CLAUDE.mdのコンテキスト管理にも同様に適用できる。CLAUDE.mdをAnthropic公式ベストプラクティスに沿って再構成した記録では、情報を「増やす加法」から「ポインタ化する減法」へ転換するプロセスを扱っている。コンテキストの整理はドキュメントだけでなくアーキテクチャでも実現できる。