転職用のポートフォリオとして、個人でWebアプリ「Hubpin」を作っています。
制作の経緯は「Hubpin 開発記録」に時系列でまとめています。
設計と判断は自分で行い、実装も原則自分で書いています。AIには手順書・レビュー・調査を任せています。
ポートフォリオ用のアプリを作るにあたって、Claude Code のセッションを2つ並行して動かしています。
| 起動場所 | 役割 | |
|---|---|---|
| 開発セッション | アプリのリポジトリ | 実装・開発ログ・設計判断の記録 |
| 秘書セッション | 管理用のディレクトリ | 工程計画・記録ルール・発信ネタの切り出し |
始めた当初は「便利そうだから」くらいの動機でした。3工程ほど回してみて、思っていたのと違う面白さが出てきたので書きます。
なぜ分けたか
ひとつのセッションで全部やろうとすると、文脈が混ざります。
工程管理の話をしていたら実装の話になり、実装の話をしていたら記事のネタの話になる。
人間の側も切り替えが追いつかなくなって、結局どれも中途半端になっていました。
分けたあとの分担はこうです。
- 開発セッション: コードを書く。開発ログに判断を残す。PRを作る
- 秘書セッション: 工程を切る。ルールを決める。ログから発信ネタを拾う
連携は共有ファイル（要件定義・工程計画）とタスク管理ツール経由で、直接はつなぎません。
やってみて気づいたことがあります。
これは実務の「ディレクターと実装者が共有ドキュメントとタスク管理ツールで連携する」構図そのものでした。
一人開発なのに、自分が両方の窓口になっている。実務未経験でも、プロセスの型だけは練習できる形になっています。
面白かったこと: ルールが改善されて戻ってきた
ここが今回の本題です。
秘書セッション側で「開発中にこれを記録してほしい」というルールを書いて、開発セッションに渡しました。
スクリーンショットをいつ撮るか、実績時間をどう記録するか、といった内容です。
開発セッションが1工程それを使って作業したら、実運用で詰まった3点が反映されて返ってきました。
1. 「バグを見つけたら直す前に撮る」は、知っているだけでは守れない
ルールには書いてありました。読んでもいます。
でも開発セッションは、バグを見つけると反射的に直しにいきます。「撮る」が独立したルールとして存在しても、修正の流れに割り込めない。
修正フローの手順1に「撮る」を固定する形に書き換えられていました。ルールとしてではなく、手順として。
2. 開発セッションには撮れない画像がある
ライトモードとダークモードを両方撮る、というルールを書いていました。
これが実行不可能でした。prefers-color-scheme はOSのテーマ設定に依存するので、ブラウザ自動化から切り替えられません。
黙って諦めずに、「開発セッションが撮れないもの」の表を作って、担当を人間に振る形になっていました。
撮影TODOに書いて依頼する、という経路まで定義されている。
3. 着手・完了の時刻を date で取ると後から検証できない
これも自分が書いたルールの穴でした。date コマンドで時刻を取る想定だったのですが、それは「思い出したときの時刻」しか取れません。
Issue の作成時刻を着手、PR の作成時刻を完了に変更されていました。gh issue view N --json createdAt で取れて、GitHubに残るので後から検証できます。
3つとも、書いた側では気づけないものでした。使った側にしか見えない。
一人で書いて一人で使っていたら、たぶん「守れなかったな」で終わっていたと思います。
別のセッションが使ったことで、守れない理由のほうが言語化されて返ってきました。
運用して分かったこと
ルールを書いただけでは守られない
当たり前のようでいて、実際に踏むまで分かっていませんでした。
AIエージェントが毎回読むのは、決まったファイル（CLAUDE.md など）だけです。
そこから参照されていないルールは、存在しないのと同じでした。
最初にルールを渡せたのは、自分が手動でパスを指定したからです。次のセッションでは読まれません。
要点と正本の場所を、毎回読むファイルに転記して初めて経路ができました。
これは人間相手でも同じだな、と思います。共有フォルダに置いただけのルールは読まれない。
申し送りは「決まった場所」に書く
直接依頼できない相手とは、置き場所を先に決めるほうが早いです。
- 開発ログの
【発信ネタ候補】マーカー → 秘書が定期的に拾う - 素材ファイルの「撮影TODO」 → 秘書が人間に依頼する
- 「未測定」の行 → デプロイ後に取得を促す
書式を決めておくと、機械的に検出できます。表記が揺れると拾えないので、マーカーの形式は統一しました。
同じファイルは追記型で書く
両方が同じファイルを触るので、追記だけにしています（上書きはしない）。変更履歴には、どちらのセッションが書いたかを明記する。
一度、実際に競合しかけました。
秘書セッションがルールを更新した2分後に開発セッションが編集して、開発側は古い内容を読んでいた、というケースです。
対策としては、編集の直前に読み直すこと。あとは git 管理下に置いておけば、事故っても git diff で戻せます。
失敗例もひとつ
いいことばかり書いてもフェアではないので、失敗も残しておきます。
開発ログの「工程5の現状」が「まだコミットしていない」のまま更新されていませんでした。
実際にはマージ済みだったのですが、秘書セッションはログを信じるので、「まだマージされていない前提」で誤った案内をしました。
古い記述は、他のセッションを間違った方向に動かします。
一人で作業していれば、自分の記憶が最新なので古い記述は無害です。読み手が別にいると、記述が唯一の情報源になる。
ドキュメントの鮮度が、そのまま相手の判断精度になります。
いまのところの結論
3工程ほど回した時点での実感です。その後も同じ分け方で続けています。
- 分けたことで文脈が混ざらなくなったのが一番大きい
- ルールは「書く」のではなく「使わせて直してもらう」ほうが速い
- 申し送りは置き場所と書式を先に決める
- ドキュメントの古さが、そのまま相手のミスになる
正直、始めたときは「2つ動かすのは管理が面倒そう」と思っていました。
実際には、面倒さの正体が「連携の設計」であって、それは実務でやっていることと同じでした。
一人でも組織的な進め方を練習できる、という点では想定以上の収穫だったと思っています。
