🏗️

AI のコードは引き継げる、判断は引き継げない — Obsidian + Claude Code 製『REFORGE』v1.0 公開

2026/04/29に公開

「1 年前の自分、この技術、なんで採用したんだっけ」
3 つ目の個人アプリを触り始めた週末、自問自答に襲われた。

GitHub の README を遡り、Obsidian のデイリーノートを漁り、Claude のチャット履歴を検索して、出てこなくて、結局同じ調査をやり直しました。
その「過去の自分に振り回される感じ」を仕組みで止めるために作ったのが REFORGE v1.0 です。今日公開します。
https://github.com/Youjinfox/REFORGE

 30 秒で「何が起こるか」仕様書 .md を Vault に分解して、過去の技術選定を 2 アプリ目以降で素材として引き取れる状態にする、Obsidian + Claude Code のスキル/コマンド集です。
同梱の examples(TaskFlow + ProjectHub のダミー仕様書)で 2 コマンド回すと、こうなります。
/vault-init $PROJECT=TaskFlow    $SPECS_DIR=./examples/taskflow/
/vault-add  $PROJECT=ProjectHub  $SPECS_DIR=./examples/projecthub/
仕様書が 要求 / プロジェクト / 概念 / インフラの 4 層に自動分類されて Obsidian ノートになる
2 アプリ共通の技術(Next.js / TypeScript / NextAuth.js など)が 概念ノートに 13 件自動昇格
同一要求に違う技術が当たっている箇所(認証・ストレージ・通知)が、4 軸で比較されたレポートとして出力
回す前に結果だけ見たい人向けに、examples/expected-output/ にスナップショットを実ファイルで置いてあります。

expected-output/taskflow/ — 1 アプリ目だけの状態

expected-output/taskflow-projecthub/ — 2 アプリ目を追加した後
差分を見比べると、概念昇格・実績追記・分析レポート出力が クローン前に 1 分で掴めます。

 こんな症状に覚えがあればひとり情シス・兼務エンジニア・フリーランス・個人でアプリを複数回している方で、こういう状態ありませんか。
同じ「ユーザー認証」をプロジェクトごとに違う方式で組んでしまう
過去に検討した代替案を思い出せず、毎回同じ調査を繰り返す
AI が書いたコードは引き継げても、「なぜその技術を選んだか」は誰も知らない
引き継ぎ資料が口伝になり、自分が抜けると何も残らない
前回の記事では、この状態を Decision Consistency Collapse(判断一貫性の崩壊) と呼び、揮発・断絶・漂流・構造的増幅の 4 症状に分解しました。詳細はそちらに譲ります。
https://zenn.dev/youjinfox/articles/170f75154f7a82
REFORGE v1.0 は、4 症状に対する 最小止血 の実装です。

 セットアップ(5 分)必要なもの:
Obsidian
Claude Code
任意:Git(コード差分検出を活かす場合)、Dataview(可視化)
git clone https://github.com/Youjinfox/REFORGE.git
cd REFORGE
Obsidian で REFORGE フォルダを Vault として開きます(初回起動画面の「フォルダを Vault として開く」、または Ctrl/Cmd+P → Open another vault)。
Claude Code でも同じフォルダを開きます。.claude/skills/ と .claude/commands/ が認識されれば準備完了です。
あとは前掲の /vault-init → /vault-add を順に実行するだけ。自分の仕様書で試す場合は $SPECS_DIR をお手元のディレクトリに差し替えてください。.md で書かれていれば厳密なテンプレートは不要です。

 コア:仕様書を 4 層に分解する/vault-init は仕様書を 4 層に分類して Obsidian ノートを生成します。


層
意味
寿命
例


要求

Why ビジネスとしての目的
10 年単位
ユーザー認証をしたい.md

プロジェクト

What アプリ固有の仕様
アプリの寿命
タスクCRUD.md

概念

How 再利用可能な技術
流行で入れ替わる
NextAuth.js.md

インフラ

Where 環境・基盤
契約と運用で変わる
Vercel本番.md

3 層でも 5 層でもなく 4 層にしたのは、寿命と再利用性が違うものを混ぜないためです。Why と How を同じ層に置くと、技術が入れ替わるたびに要求まで巻き込まれます。逆に層を増やしすぎると、AI による分類判定がブレます。4 層がギリギリの境界でした。

 2 アプリ目で、本領が出るREFORGE が一番効くのは 2 アプリ目を追加したときです。1 アプリ目で並べた素材が、2 アプリ目で打ち直せるタイミングだからです。
/vault-add を実行すると、自動でこうなります。
共通する要求ノートに 2 行目が積層(認証ノートに「TaskFlow → email/password」「ProjectHub → Magic Link」が並ぶ)
両アプリで使われている技術が 概念ノートに自動昇格、双方向リンクが張られる
同一要求に違う技術が当たっている箇所が検出され、4 軸(セキュリティ / UI・UX / 保守性 / コスト)で定量比較される
examples で実際に流すと、TaskFlow(Supabase + Email/Password)と ProjectHub(Neon + Magic Link)の間で、概念ノートが 13 件昇格、分析レポートが 1 件自動生成 されます(ファイル添付は AWS S3 統一推奨、通知は Slack と SendGrid で保留、など、判断まで出力されます)。
数値根拠(CVE 件数、GitHub Stars、月額無料枠など)は 照合日とセットで 出力されます。「いつ計測したか」が消えるとデータが嘘になるので、根拠なしの推奨は出さない設計にしました。

 コマンドは 6 つだけ

コマンド
用途


/vault-init
初回構築

/vault-add
2 つ目以降を追加。概念昇格 + 統一分析

/vault-update
コード/仕様書の差分から Vault を同期(Git/非 Git 自動判定)

/vault-analyze
統一分析を任意実行

/vault-add-requirement
要求ノートを単独追加

/vault-status
Vault 状態のサマリー(読み取り専用)

機能を増やすより、迷わず動く最小セットを優先しました。

 設計の根っこ:鍛冶場(Forge)REFORGE という名前は、REusable Framework for Organized Reference & Growth in Engineering の頭字語であると同時に、動詞 "reforge"(打ち直す・鍛え直す)を重ねています。
Vault を 自分専用の鍛冶場(Forge) だと考えてみてください。過去のアプリで採用した技術、却下した技術、その理由、参照した数値根拠が、素材として並んでいる作業場です。新しいアプリを作るとき、白紙から始めるのではなく、いつもこの鍛冶場に戻ります。
AI が書いたコードは引き継げる。AI が下した判断は引き継げない。
リポジトリ README に置いた一行で、本記事のタイトルにもしています。REFORGE が仕組み化したい一番の動機はここにあります。コードは GitHub に残っても、「なぜその技術を選んだか」「どの代替案を否決したか」「当時の数値根拠は何だったか」は書いた本人の頭にしか残りません。退職・異動・チーム拡大で抜けた瞬間、後任は同じ調査をゼロからやり直すことになります。
Vault フォルダごと譲れば、判断のコードだけでなく、判断の文脈と検証可能性ごと譲れる。これが Forge メタファーの意図です。

 補足リンク(本記事から逃した話)
拡張ロードマップ(神経科学インスパイアの v2.0:/consolidate / /revisit / /pain):ROADMAP.md

Harness Engineering との関係(ignission 氏のフロー自動化方法論。コード品質は Harness、判断の一貫性は REFORGE で、レイヤーが違うため併用可):Harness Engineering

フロントマターを日本語キーにした理由(オーナーと引き継ぐ相手が読めることを最優先した明示的な判断。妥協ではない):README に記載

前回記事(Decision Consistency Collapse の 4 症状):https://zenn.dev/youjinfox/articles/170f75154f7a82

 ライセンスとフィードバック
ライセンス: CC BY 4.0

リポジトリ: https://github.com/Youjinfox/REFORGE

フィードバック: GitHub Issues / Discussions
改変・再配布・商用利用すべて自由。「REFORGE Contributors」の明示だけお願いしています。

 おわりに「過去の自分が下した判断を、未来の自分が引き取れる形に整えたい」。そんな感覚に覚えがあれば、まず examples/expected-output/ を 1 分眺めてみてください。examples を実際に走らせるなら 5 分です。
「自分の現場ではこう揮発している」「この症状は扱えていない」という声は、そのまま v2.0 の設計材料になります。Issues / Discussions でお待ちしています。

層	意味	寿命	例
要求	Why ビジネスとしての目的	10 年単位	`ユーザー認証をしたい.md`
プロジェクト	What アプリ固有の仕様	アプリの寿命	`タスクCRUD.md`
概念	How 再利用可能な技術	流行で入れ替わる	`NextAuth.js.md`
インフラ	Where 環境・基盤	契約と運用で変わる	`Vercel本番.md`

コマンド	用途
`/vault-init`	初回構築
`/vault-add`	2 つ目以降を追加。概念昇格 + 統一分析
`/vault-update`	コード/仕様書の差分から Vault を同期(Git/非 Git 自動判定)
`/vault-analyze`	統一分析を任意実行
`/vault-add-requirement`	要求ノートを単独追加
`/vault-status`	Vault 状態のサマリー(読み取り専用)