Claude Codeのセッション記憶喪失問題を解決し続けたら、開発が劇的に変わった話

はじめに

Claude Codeを使い始めてしばらく経つと、誰もがぶつかる壁があります。

「さっきまで完璧に理解してくれていたのに、新しいセッションを開いたら全部忘れている」

プロジェクトの背景を説明し直す。コーディング規約を再度伝える。さっき試して失敗したアプローチをまた提案される。この繰り返しに心当たりはないでしょうか。

MEMORY.mdの仕組みも最近追加されましたが、後で述べますが色々と課題があります。

私も最初はこの「記憶喪失ループ」に悩まされていました。CLAUDE.mdにルールを書く。MEMORY.mdに経験を蓄積させる。それでもセッションをまたぐと文脈が途切れる。

また私の場合、日中は会社のPC、夜間は自宅のPCで作業を継続しますが、Claude CodeのMEMORY.mdはリポジトリ内にないためメモリを引き継げません。さらにはCodexなど別のCLIやIDEに作業を切り替えたい場合も同様です。

これらの問題を解決しようと試行錯誤を続けた結果、設定ファイルの分業体制、CLI/IDE中立設計、仕様駆動開発、そしてスキルによる開発環境構築の自動化という一連の仕組みが出来上がりました。記憶喪失の解決から始まった取り組みが、気づけば開発ワークフロー全体を変えていたのです。

この記事では、その設計思想と具体的な実装方法を、実際のスキルファイル付きで共有します。

---

1. MEMORY.mdの功罪

そもそもMEMORY.mdとは

Claude Codeには2種類の設定ファイルがあります。CLAUDE.mdは「人間が書く指示書」、MEMORY.mdは「AIが自分で書く記憶」です。MEMORY.mdはセッション中にAIが学んだ教訓やパターンを自動で記録してくれる仕組みで、使い込むほど賢くなるという理想的な設計に見えます。

しかし、実際に運用してみると4つの問題が浮き彫りになりました。

問題① 200行ハードリミット

MEMORY.mdは200行を超えるとトランケートされます。このハードリミットはClaude Code側の制約で、ユーザーが変更することはできません（2026年3月時点）。

AIが経験を書き続けると、重要な記憶が末尾に追いやられて切り捨てられるという逆説が起きます。「記憶を蓄積するための仕組みが、記憶を失う原因になる」という皮肉な状況です。

問題② CLAUDE.mdとの重複

MEMORY.mdにはCLAUDE.mdと同じ内容が重複して書き込まれることがよくあります。これにより：

• AIが「どちらが正しいか」と迷う 注意の分散
• 200行の枠を重複で消費する 行数の浪費
• 片方だけ更新されて矛盾が生まれる 更新の不整合

の4つの問題が同時に発生します。

問題③ コンパクション後の劣化

Claude Codeはコンテキストが95%を超えると自動圧縮（Auto-compact）が走ります。これは会話履歴をAIが要約して置き換える処理ですが、圧縮を繰り返すと「要約の要約の要約」になり、細部が失われていきます。

MEMORY.mdも「自律的にゴミを量産する」状態に陥ることがあり、AIの行動品質が明確に劣化するケースが報告されています。

問題④ マルチPC、マルチCLI/IDEに対応不可

現在Claude CodeのMEMORY.mdはリポジトリとは別管理です。そのため作業するPCが代わるとメモリや作業セッションが引き継げません。同様にツールをCodexやAntiGravityに切り替えた際も、セッションの状況説明が都度必要となります。

この章のポイント: MEMORY.mdは便利だが、放置すると記憶の質が劣化するジレンマを内包している。「AIに自由に書かせすぎない」仕組みが必要。

---

2. 3ファイル体制の設計

記憶喪失問題の根本原因

問題の本質は「1つのファイルに複数の役割を詰め込んでいること」でした。CLAUDE.mdにルールも経験も引き継ぎも書いてしまうと、情報が混在して管理できなくなります。

そこで辿り着いたのが、役割を明確に分離した3ファイル体制です。

ファイル	書き手	性質	内容
AGENTS.md	人間	不変のルール	プロジェクト規約・振る舞いの指示
MEMORY.md	AI	積み上がる経験	学習した教訓・経験知
HANDOFF.md	AI（人間がレビュー）	セッション間の引き継ぎ	今やっていたことの引き継ぎ

なぜこの3つなのか

AGENTS.md（不変のルール） は人間が書いて管理します。プロジェクトのコーディング規約、使用言語、AI への振る舞い指示など、セッションをまたいでも変わらない情報を置きます。AIは読むだけで、書き換えません。

MEMORY.md（積み上がる経験） はAIが自動で書く学習記録です。ただし、200行制限への対策として以下のルールを設けました：

• AGENTS.mdと重複する内容は書かない
• 更新前に日付アーカイブを作成する（YYYY-MM-DD.md）
• インデックス（目次）として使い、詳細は必要に応じて別ファイルに分離する

HANDOFF.md（セッション間の引き継ぎ） がこの設計の要です。MEMORY.mdとの決定的な違いは、人間がレビューしてキュレーションできる点にあります。

AIが自動で書くMEMORY.mdは内容が汎用的・冗長になりがちですが、HANDOFF.mdは「本当に必要な引き継ぎ情報だけ」を人間がフィルタリングできます。セッション終了前にAIが作成し、人間がレビューして不要な情報を削ぎ落とす。この「人間がキュレーションする」プロセスが、記憶の質を維持する鍵です。

運用ルール

HANDOFF.mdは固定名で常に最新版を保持し、作成時に前回のファイルをタイムスタンプ付きでアーカイブします：

.agent/handoff/
├── HANDOFF.md              ← 常に最新（AIが読む）
├── 2026-03-02-1845.md      ← アーカイブ（人間が経緯確認用）
└── 2026-03-01-0930.md

AIへの指示：

• 現在のPCやCLI/IDEでの作業終了時に/handoffコマンドを実行すると今回のセッションで行ったことをHANDOFF.mdに保存
• 再開時は「セッションを再開して」の一言でHANDOFF.mdを自動的に読み出し

HANDOFF.mdやアーカイブは、人間がAIの実行内容や「なぜその判断をしたか」などを追跡するための資産になります。

---

3. マルチPC・マルチCLI/IDE対応

なぜ .agent/ フォルダなのか

ここまでの設計をさらに進めると、次の疑問が生まれます：

• 会社PCと自宅PCで作業を継続したい（マルチPC）
• CLIやIDEを切り替えても自動的に作業を継続したい（マルチCLI/IDE）

MEMORY.mdとHANDOFF.mdを .claude/ フォルダに置くと、Claude Code固有のディレクトリになってしまいます。Codex CLIやAntiGravity、Gemini CLI等は .claude/ を読みにいきません。

そこで、.agent/ というCLI中立なフォルダにMEMORYとHANDOFFを配置する設計にしました。

各CLIの設定ファイル（CLAUDE.md / AGENTS.md / GEMINI.md）にはそれぞれ「.agent/memory/MEMORY.md と .agent/handoff/HANDOFF.md を読むこと」と共通の指示を書いておきます。ツール固有の差分だけを各設定ファイルに記載し、共通ルールはAGENTS.mdに集約します。

AGENTS.mdを本体として、CLAUDE.mdやGEMINI.mdには「AGENTS.mdを読め」とだけ書くのもシンプルでお勧めです。

マルチPC対応

私の場合、作業ディレクトリをOneDriveで同期しています。.agent/ フォルダもリポジトリ内にあるため、OneDriveで自動同期されます。

• 作業中のファイル同期: OneDrive（リアルタイム）
• バージョン管理: Git/GitHub（区切りのいいタイミング）

セッション固有のローカル情報（セッションID、トランスクリプト等）はClaude Codeのデフォルト保存先（~/.claude/）にそのまま残るため、同期の競合も起きません。PCやCLI/IDEを切り替える前に/handoffコマンドを実行するとHANDOFF.mdが自動生成され、別のPCやCLI/IDEですぐに作業を再開できます。

---

4. 仕様駆動開発（SDD）

記憶の管理から、作業の管理へ

3ファイル体制で記憶喪失問題は解決できました。しかし、使い込んでいくうちに別の課題が見えてきました。

「AIが指示を理解してくれるのに、アウトプットの品質がばらつく」

原因は明確でした。人間の指示が曖昧なまま作業に入っているからです。AIの理解力が上がるほど、曖昧な指示でもそれなりに動いてしまう。結果として「意図と違うものが高速に出来上がる」という新たな問題が生まれていました。

そこで導入したのが、仕様駆動開発（Spec-Driven Development: SDD） です。

4ファイル体制

.spec/ フォルダに以下の4ファイルを配置します：

ファイル	役割	書き手
PLAN.md	やりたいことの自由メモ	人間
SPEC.md	要件定義・技術仕様	AIが構造化（人間が承認）
TODO.md	タスクリスト	AIが分解（人間が承認）
KNOWLEDGE.md	調査結果・決定理由の記録	AI

重要なポイント：PLAN.mdは「雑でいい」

PLAN.mdには見出しテンプレートを一切設けていません。代わりにこう書いてあるだけです：

# PLAN - やりたいこと

<!-- ここに思ったことを自由に書いてください。箇条書きでも口語でもOK -->
<!-- Claude がこの内容を読んでヒアリングし、SPEC.md を作成します -->

「かっちりしたテンプレート」があると、人間側に「ちゃんと書かなきゃ」という心理的ハードルが生まれます。PLAN.mdは口頭メモ、断片的な思いつき、箇条書きの羅列で十分です。それをAIが読んでヒアリングし、対話を通じてSPEC.mdを構造化していく。このフローにしたことで、「仕様を書く」という行為のハードルが劇的に下がりました。

AGENTS.mdへの組み込み

SDDのルールはAGENTS.mdに以下のように記載します：

## 仕様駆動開発（SDD）ルール
- コーディングや業務作業を開始する前に、必ず `.spec/` 配下の4ファイルを確認・更新すること
- 作業の順序：PLAN（目的確認）→ SPEC（要件確認）→ TODO（タスク確認）→ 実作業
- **PLAN.mdは人間の口頭メモ・自由記述**であり、箇条書き・口語・断片的な内容で構わない
- PLAN.mdを読んだら、そのまま実装に入らず、不明点をヒアリングしながらSPEC.mdを作成・確定させること
- SPEC.mdが確定してからTODO.mdのタスク分解を行い、ユーザーの承認を得てから実作業を開始する

これにより、どのCLIやIDEを使っても「いきなりコードを書き始める」ことがなくなります。

次の開発も簡単に進む newplan コマンド

SDDで開発を進める場合、機能追加を行う度に、プラン作成→仕様策定→ToDo実行のループが都度繰り返される事にも対応しています。

本記事のスキルで実現している解決策は、前記したメモリやハンドオフのアーカイブ処理同様に、新規開発と過去の開発を明確に分離し、それぞれ保存する仕組みです。

具体的には/newplanコマンドを追加しており、このコマンドを発令すると直前のPLAN.md、SPEC.md、TODO.mdをアーカイブした上で新たに一式を作成します。

この新たに作成されたPLAN.md、SPEC.md、TODO.mdを、次の開発で再び利用するという手順を繰り返し行えますので、SDDの過去の開発の経緯もアーカイブファイルを閲覧すれば全て見返せますし、AIに要点を聞くのもお勧めです。

---

5. スキルで全部自動化

毎回手動で構築するのは非現実的

ここまでの設計は強力ですが、新しいプロジェクトを立ち上げるたびに以下を手動で行うのは非現実的です：

• .agent/ 配下のフォルダ・ファイル作成
• .spec/ 配下の4ファイル作成
• AGENTS.md / CLAUDE.md / GEMINI.md の作成
• .claude/commands/handoff.md の作成
• .claude/commands/newplan.md の作成
• .gitignore の設定
• Git初期化

そこで、Claude Codeのスキル機能を使って、これらを一発で実行できるようにしました。

スキルとは

Claude Codeのスキルは、特定のタスクをClaude Codeに実行させるための定義ファイルです。マークダウンで手順を記述すると、Claude Codeがその手順に従って自動実行してくれます。

使い方

この記事はClaude Codeが高品質の記事を自動生成するインパクトを伝える目的もあり当初は生成されたままのスキルを掲載していましたが、多くの方に読んで頂いていることもあり、私が手を加えた「使えるスキル」に更新しました。

新規プロジェクト構築＞

1. グローバルスキルが入っているフォルダに下記のSKILL.md全文をmake_projectスキルとして配置する
2. 新規プロジェクトフォルダの親フォルダでClaude Codeを起動する
3. 「プロジェクトを初期化して」と指示する

たったこれだけで、新規プロジェクトのフォルダ作成 + 3ファイル体制 + SDD + Git初期化が完了します。完了後は一旦終了して新規プロジェクトに入り直して下さい。

グローバルスキルの場所：Cluade Codeの場合は下記の全文を ~/.claude/skills/make_project/SKILL.mdで保存します。Codexで行う場合は、~/.agents/skills/make_project/SKILL.md に同様に保存します。

開発中のプロジェクトでも利用できます。 その場合はプロジェクト内で「make_projectスキル発動」と指示すると、対話機能を介して不足分を追加実装する動作になります。但し、思わぬ動作になる可能性もあるため、導入前に必ずスキル全文に目を通して下さい。また不具合に関しては保証しかねます。

SKILL.md 全文

以下が実際に使用しているスキルファイルの全文です。コピペしてそのまま使えます。

make_project スキル（クリックで展開）

---
name: make_project
description: 新規プロジェクトの初期構築を行うスキル。新規プロジェクトのセットアップ、初期ファイル作成、Git初期化、既存プロジェクトのアップデートを行う際に使用する。「プロジェクトを初期化して」「新規プロジェクトをセットアップして」「プロジェクトの初期構築をして」「プロジェクトをアップデートして」などのリクエストに対して必ず使用すること。
---

# make_project スキル

## ステップ1：モード選択

作業を開始する前に、ユーザーに以下を必ず口頭で提示し、番号で選択してもらうこと：

「make_project スキルを開始します。以下から実行モードを選択してください：

1. 新規プロジェクトを構成する（現フォルダの中に新規プロジェクトフォルダを作成）
2. 既存のプロジェクトをアップデートする（現フォルダをプロジェクトフォルダとして使用）
3. その他・相談する

番号を入力してください。」

- **1を選択** → 「モードA：新規プロジェクト作成」へ進む
- **2を選択** → 「モードB：既存プロジェクトのアップデート」へ進む
- **3を選択** → 「モードC：対話」へ進む

---

# モードA：新規プロジェクト作成

## A-1. 事前確認
以下の情報をユーザーに確認してから作業を開始する：
- プロジェクト名（フォルダ名）：[USER_INPUT]
- GitHubリポジトリURL：[USER_INPUT]
- デフォルトブランチ名：main（変更がある場合はユーザーに確認）

※ 事前にGitHub上でリポジトリを作成しておくこと（README等は追加しない）

## A-2. プロジェクトフォルダの作成

\```bash
mkdir [PROJECT_NAME]
cd [PROJECT_NAME]
\```

以降の作業はすべてこのフォルダ内で実行する。

## A-3. サブフォルダ作成

\```bash
mkdir -p .agent/skills
mkdir -p .agent/memory
mkdir -p .agent/handoff
mkdir -p .agent/workflows
mkdir -p .claude/commands
mkdir -p .spec
mkdir -p .output
mkdir -p .references
\```

## A-4. 初期ファイル作成

### README.md

README.mdが存在しない、あるいは中身が空の時のみ以下を実行する。
プロジェクト名はA-1で確認済みのものを使用する。日時はローカル時刻、ツール名は現在使用中のツール名（例：Claude Code Opus 4.6）を記載する。

\```bash
cat << 'EOF' > README.md
# Project: [PROJECT_NAME]

* これは[YYYY-MM-DD HH:MM]に自動生成されたプロジェクトである
* 初期構築担当ツール名：[TOOL_NAME]
* このプロジェクトでは、生成AIおよびスキルを積極的に活用して開発する
EOF
\```

### .agent/memory/MEMORY.md
\```bash
cat << 'EOF' > .agent/memory/MEMORY.md
# MEMORY

## プロジェクト概要

## 学習した知識・教訓
EOF
\```

### .agent/handoff/HANDOFF.md
\```bash
cat << 'EOF' > .agent/handoff/HANDOFF.md
# HANDOFF

初回セットアップ完了。作業を開始してください。
EOF
\```

### CLAUDE.md（プロジェクトルート）
\```bash
cat << 'EOF' > CLAUDE.md
- セッション開始時に共通ルールである、AGENTS.mdを必ず読み込むこと。
- 読み込んだことを最初に報告すること
- 以下は Claude Code固有の差分のみ記載する
EOF
\```

### GEMINI.md（プロジェクトルート）
\```bash
cat << 'EOF' > GEMINI.md
- セッション開始時に共通ルールである、AGENTS.mdを必ず読み込むこと。
- 読み込んだことを最初に報告すること
- 以下は Gemini 固有の差分のみ記載する
EOF
\```

### AGENTS.md（プロジェクトルート）
\```bash
cat << 'EOF' > AGENTS.md
# Project guide line

## プロジェクトの原則
- 本プロジェクトのプラン作成、および回答は全て日本語で行う

## プロジェクトの目的
- 

## Local Skills
- セッション開始時にプロジェクトのローカルスキルを `.agent/skills/` 配下で確認する

# Memory & Handoff Instructions

## 3ファイルの役割と哲学
- 本ファイル（AGENTS.md）は「厳格なルール」、人が作成
- MEMORY.mdは「積み上がる経験」、AIが作成・AIが利用
- HANDOFF.mdは「セッション間の引き継ぎ」、AIが作成・AIが利用、ただし人間がレビューし必要な情報をキュレーションする

## セッション開始時（必須）
セッション開始時、ユーザーへの最初の応答の前に、以下の2ファイルを読み込み、読み込んだことを報告すること：
- `.agent/memory/MEMORY.md`  （学習した知識・教訓）
- `.agent/handoff/HANDOFF.md` （前回の作業引き継ぎ）

## メモリ管理
- 新しい知識・教訓を記録する際は `.agent/memory/MEMORY.md` を更新
- 既存のMEMORY.mdを更新する前に、現在のファイルを`.agent/memory/YYYY-MM-DD.md` にアーカイブしてから新規作成
- ローカルの自動メモリ機能（~/.claude/ 配下）は使用しない
- MEMORY.mdは200行以内を維持すること
- 本ファイルと重複する内容はMEMORY.mdに書かない

## ハンドオフ管理
- ハンドオフは `/handoff` コマンドで作成（Claude Codeの場合）
- 保存先は `.agent/handoff/HANDOFF.md`（固定名）
- 作成時は既存ファイルを `.agent/handoff/YYYY-MM-DD-HHMM.md` にリネームしてからHANDOFF.mdを新規作成する
- 時刻はローカル時刻・24時間表記

## 仕様駆動開発（SDD）ルール
- コーディングや業務作業を開始する前に、必ず `.spec/` 配下の4ファイルを確認・更新すること
- 作業の順序：PLAN（目的確認）→ SPEC（要件確認）→ TODO（タスク確認）→ 実作業
- **PLAN.mdは人間の口頭メモ・自由記述**であり、箇条書き・口語・断片的な内容で構わない
- PLAN.mdを読んだら、そのまま実装に入らず、不明点をヒアリングしながらSPEC.mdを作成・確定させること
- SPEC.mdが確定してからTODO.mdのタスク分解を行い、ユーザーの承認を得てから実作業を開始する
- 作業完了後は TODO.md の該当タスクにチェックを入れ、KNOWLEDGE.md に学びを記録する
- 仕様が不明確な場合は作業を開始せず、ユーザーに確認してから SPEC.md を更新する
- 新しい開発サイクルを始める際は `/newplan` コマンドを使用する

## フォルダ用途
- `.spec/`：設計ドキュメント（PLAN / SPEC / TODO / KNOWLEDGE）
- `.output/`：成果物・アウトプット（記事MD、コード、資料など完成したもの）
- `.references/`：参考資料・素材（PDFや画像、URLメモ、サンプルコードなど作業の入力素材）
EOF
\```

## A-5. 仕様駆動開発ファイルの作成（.spec/）

### .spec/PLAN.md
\```bash
cat << 'EOF' > .spec/PLAN.md
# PLAN - やりたいこと

<!-- ここに思ったことを自由に書いてください。箇条書きでも口語でもOK -->
<!-- Claude がこの内容を読んでヒアリングし、SPEC.md を作成します -->
EOF
\```

### .spec/SPEC.md
\```bash
cat << 'EOF' > .spec/SPEC.md
# SPEC - 技術仕様・要件定義

## 機能要件
## 非機能要件
## 技術構成
EOF
\```

### .spec/TODO.md
\```bash
cat << 'EOF' > .spec/TODO.md
# TODO - タスクリスト

## 優先度：高
## 優先度：中
## 優先度：低
## 完了済み
- [x] 初期セットアップ
EOF
\```

### .spec/KNOWLEDGE.md
\```bash
cat << 'EOF' > .spec/KNOWLEDGE.md
# KNOWLEDGE - ドメイン知識・調査結果

## 業務・ドメイン知識
## 調査・リサーチ結果
## 技術的な知見
## 決定事項と理由
EOF
\```

## A-6. newplan コマンドの作成

\```bash
NEWPLAN_CONTENT='以下の手順で新しい開発サイクルを開始してください：

1. `.spec/` 配下の4ファイルが存在する場合、本日の日付（ローカル時刻）でアーカイブする：
   - `PLAN.md`      → `PLAN-YYYY-MM-DD.md`      にリネーム
   - `SPEC.md`      → `SPEC-YYYY-MM-DD.md`      にリネーム
   - `TODO.md`      → `TODO-YYYY-MM-DD.md`      にリネーム
   - `KNOWLEDGE.md` → `KNOWLEDGE-YYYY-MM-DD.md` にリネーム

2. 新しいファイルを以下の通り作成する：
   - `PLAN.md`：空テンプレートで新規作成
   - `SPEC.md`：空テンプレートで新規作成
   - `TODO.md`：空テンプレートで新規作成
   - `KNOWLEDGE.md`：アーカイブした内容をそのままコピーして新規作成（知見を引き継ぐ）

3. 完了後、以下を報告する：
   - アーカイブしたファイル一覧
   - 「新しいPLAN.mdにやりたいことを自由に書いてください」'

printf '%s\n' "$NEWPLAN_CONTENT" > .claude/commands/newplan.md
printf '%s\n' "$NEWPLAN_CONTENT" > .agent/workflows/newplan.md
\```

## A-7. handoff コマンドの作成

\```bash
HANDOFF_CONTENT='以下の手順でハンドオフを作成してください：

1. `.agent/handoff/HANDOFF.md` が存在する場合：
   - そのファイルの更新日時（ローカル時刻）を取得
   - `.agent/handoff/YYYY-MM-DD-HHMM.md` にリネーム

2. 新しい `.agent/handoff/HANDOFF.md` を以下のテンプレートに従って作成し、完了後「HANDOFF.mdを作成しました」と報告してください。各項目には、現在までのチャット履歴や作業内容からAI自身が自己の行動を要約し、具体的な内容を記入してから保存してください。単なる空のテンプレートのまま保存してはいけません。

---
# HANDOFF - {日時}

## 使用ツール
Claude Code / Codex CLI / Gemini CLI など、該当するツール名を記載

## 現在のタスクと進捗
- [ ] タスク名：現在の状況

## 試したこと・結果
- 成功したアプローチ
- 失敗したアプローチ（理由）

## 次のセッションで最初にやること
1. 最初のアクション
2. 次のアクション

## 注意点・ブロッカー
- 注意すべき事項
---'

printf '%s\n' "$HANDOFF_CONTENT" > .claude/commands/handoff.md
printf '%s\n' "$HANDOFF_CONTENT" > .agent/workflows/handoff.md
\```

## A-8. Git初期化

### .gitignore の作成
\```bash
cat << 'EOF' > .gitignore
# Logs
logs
*.log

node_modules
dist
dist-ssr
*.local

# Editor directories and files
.vscode/*
!.vscode/extensions.json
.idea
.DS_Store
.env
EOF
\```

### Git初期化とpush
\```bash
git init
git add .
git commit -m "first commit"
git remote add origin [USER_INPUT]
git push -u origin main
\```

## A-9. 完了報告

全手順完了後、以下を報告する：
- 作成したファイル・フォルダの一覧
- GitHubへのpush結果
- 次のステップの案内（「一旦このプロジェクトを終了し、新規作成したプロジェクトに入り直して下さい。新規プロジェクトのAGENTS.mdにプロジェクト概要を記載し、PLAN.mdにやりたいことを書いてください」など）

---

# モードB：既存プロジェクトのアップデート

## B-1. 現状の精査

本スキル（make_project）のモードAのA-3以降に記載されているすべての要素を正として、
現在のプロジェクトフォルダの状態と照合し、不足・未作成の要素をリストアップする。

精査完了後、以下を報告する：
「以下の差分が見つかりました。アップデートを適用してよいですか？
- 追加・作成するもの：[不足している要素の一覧]
- スキップするもの（既存）：[すでに存在する要素の一覧]」

ユーザーの承認を得てから B-2 に進む。

## B-2. 差分の適用

B-1で不足と判定された要素のみ、モードAの対応する手順を実行する。
既存ファイル・フォルダは上書きしない。
AGENTS.mdへの追記は既存内容と重複しないよう確認してから行う。

## B-3. 完了報告

適用した内容とスキップした内容の一覧を報告する。

---

# モードC：対話

ユーザーの相談内容をヒアリングし、このスキルの範囲でできることを提案する。
必要に応じてモードAまたはモードBへ誘導する。

---

6. 実際の開発がどう変わったか

Before（導入前）

項目	状況
セッション開始時	毎回5〜10分の背景説明
PC切り替え	セッション内容を人間が記憶して再開
CLI/IDE切り替え	1からプロジェクト構造を説明し直す
仕様の管理	チャット履歴を遡って確認
新規プロジェクト	毎回手動でファイル・フォルダを作成
プロジェクト開始	詳細な要件定義を作成してから開始
プロジェクト更新	都度同様の手順を行う

After（導入後）

項目	状況
セッション開始時	「作業を再開して」の一言で即開始
PC切り替え	/handoff → OneDrive同期 → 即再開
CLI/IDE切り替え	/handoff → CLI/IDE切替 → 即再開
仕様の管理	SPEC.mdを見れば常に最新の仕様がわかる
新規プロジェクト	「プロジェクト初期化して」の一言で完了
プロジェクト開始	PLAN.mdにやりたい事を書いて開始
プロジェクト更新	/newplan → PLAN.mdに書いて開始

スキルの力で開発環境一式が即揃い、口頭レベルでPLAN.mdにやりたいことをつらつらと書いて指示するだけ。実はこの記事も、本記事掲載のスキルで環境を構築し、「今回の課題解決一式をQiitaの記事を作成して」と記載したPLAN.mdを基にClaude Codeが作成したものです。

最も大きな変化は 「AIに何を伝えるか」から「AIと何を作るか」に集中できるようになった ことです。

記憶喪失の問題が解消されると、セッションの最初から「本題」に入れます。文脈の再構築に使っていた時間がゼロになり、純粋な作業時間に充てられるようになりました。

また、仕様駆動開発を組み込んだことで、「AIが曖昧な指示を独自解釈して突っ走る」という問題もなくなりました。PLAN.mdに雑なメモを書くだけで、AIがヒアリングして仕様を固めてくれる。この「AIとの壁打ちで仕様が磨かれていく」体験は、一人開発でも設計品質を維持できる強力な仕組みです。

---

7. まとめ

この記事で紹介した仕組みを整理します。

解決した問題と解決策：

1. セッション記憶喪失 → 3ファイル体制（AGENTS.md / MEMORY.md / HANDOFF.md）
2. マルチPC・マルチCLI/IDE対応 → .agent/ フォルダによるCLI/IDE中立設計
3. アウトプット品質のばらつき → 仕様駆動開発（PLAN → SPEC → TODO）
4. 毎回の手動セットアップ → スキルによる一発自動化

記憶喪失という一つの問題を解決しようとしたら、ファイル設計、CLI/IDE中立設計、仕様管理、自動化と、開発ワークフロー全体が整理されていきました。

スキルファイルは本記事内に全文を掲載していますので、コピペしてすぐに試せます。「プロジェクトを初期化して」の一言で、この記事で紹介したすべての仕組みが立ち上がります。

ぜひ、あなたのプロジェクトでも試してみてください。

※私の環境(MacやWindows）では、以下で動作を確認済みです。

1. ターミナル版：Claude Code、Codex CLI、Gemini CLI、GitHub Copilot CLI
2. IDE環境版：VSCode(+GitHub Copilot)、AntiGravity、Cursor、Kiro、
3. Mac&Windowsデスクトップ版：Claude Code、Codex
4. web版：Claude Code、Codex