作業メモと決定をリポジトリの中に残す：AIと共有する in-repo 方式

IRN MarkdownGitHub

Claude Code と作業していると、「なぜこの方式にしたのか」「あのとき何を調べたのか」がどんどん積み上がる。それをどこに置くか、という話。

結論は単純で、作業しているリポジトリの中に Markdown で置く。専用のツールもサービスも要らない。GitHub に置けば、そのまま Wiki のように読める。

1. はじめに

1-1. 何が困るか

AIエージェントとの作業では、放っておくと情報が消える場所が3つある。

セッションをまたぐと経緯が消える：新しいセッションの Claude は、前回どんな案を検討して何を捨てたかを知らない。同じ調査をもう一度させることになる
CLAUDE.md に全部書くと肥大する：常駐の指示ファイルは毎回読み込まれるので、太らせるほど1回あたりのコストが上がり、肝心の指示が埋もれる
エージェントごとに記憶が分かれる：Claude Code と Codex では記憶の置き場所が別。片方に貯めたものはもう片方から見えない（→ §8）

1-2. 置き場所をリポジトリの中にする

in-repo 方式：調査メモや知見を、専用ツールではなく対象リポジトリの中に素の Markdown で置き、git で版管理し、AIエージェントが直接読み書きするやり方。

in-repo 方式と名前を付けてはいるが、発明でも独自手法でもない。リポジトリの中に Markdown を置いて git で管理する、というだけのことで、多くの開発者が名前を意識せずに同じことをやっている。毎回長い説明を書かずに済ませるためのラベル。

この方式の利点は3つ。

clone すれば記憶も付いてくる：別のマシンでも、履歴ごとそのまま手に入る
どのエージェントからも読める：Claude Code でも Codex でも、ただのファイルなので普通に読める
git の履歴が残る：いつ考えが変わったかが後から追える

1-3. 前提：GitHub で管理する、Private がおすすめ

この方式は git で版管理することが前提。GitHub に置いておけば、閲覧・検索・履歴がブラウザだけで完結する（→ GBA）。

リポジトリは Private にしておくのがおすすめ。記事やアプリのコードと違って、メモは書くときに公開を意識しない。公開前のURL、どのアカウントで認証しているか、人の名前、ボツにした案。そういうものが自然と混ざる。後から Public に切り替えるのは簡単だが、逆は履歴が残るので取り返しがつかない（→ GBA 6-2）。

2. まず notes/ ひとつから始める

最初の構成はこれだけでよい。

myproject/
  CLAUDE.md
  notes/
    d1-vs-kv-2026-08-01.md
    login-key-research-2026-08-05.md
  （以下、アプリのファイル）

CLAUDE.md：毎回読ませるルール。短く保つ
notes/：経緯そのもの。調査・計画・下書き・ボツ案。厚くてよい

分担は「毎回読ませるものは短く、詳しい話は notes/ へ」。CLAUDE.md に判断の背景まで書くと、肝心のルールがその中に埋もれる。

使い方は、調べものをしたあとに一言頼むだけ。

いま調べた内容を notes/ にメモとして残して。ファイル名は内容がわかる英語に日付を付けて。

3. 書き方の決めごと

決めごとは少ないほうが続く。4つだけ。

3-1. 1テーマ1ファイル、フラットに置く

サブディレクトリは作らない。テーマ別に切りたくなるが、「どの階層に入れるか」を毎回考えるコストのほうが高い。ファイルが増えて一覧しづらくなったら、フォルダを切るのではなく索引で吸収する（→ §7-1）。

3-2. ファイル名は `<topic>-<YYYY-MM-DD>.md`

例：login-key-research-2026-08-05.md。日付は、そのメモを書いた（検討した）時点。

ファイル名だけで「何を・いつ」が分かるので、一覧しただけで目当てのメモが探せる。

topic は英数字とハイフンにしておくのがおすすめ。 中身は日本語でよく、これはファイル名だけの話。日本語のファイル名でも問題なく動くが、地味に効く不便が2つある。

1つは、git status や git log で読めなくなること。git は既定で非ASCIIのファイル名をエスケープして表示する。

?? "\343\203\255\343\202\260\343\202\244\343\203\263\343\202\255\343\203\274\343\201\256\350\252\277\346\237\273-2026-08-05.md"

git config --global core.quotepath false で直せるが、そのリポジトリを触るマシン全部で設定することになる。もう1つは、GitHub の URL が長くなること。日本語の部分がパーセントエンコードされるので、リンクを貼ったりチャットに流したりしづらい。

とはいえ日本語にしたくなる理由は「英語のファイル名を考えるのが面倒」に尽きるので、そこは Claude に任せてしまえばよい。「内容がわかる英語のファイル名で」と頼めば付けてくれる。「一覧して意味がすぐ分かってほしい」という要求のほうは、索引（→ §7-1）が引き受ける。

あくまでおすすめなので、上の不便を承知のうえで日本語のファイル名にしたいなら、そう伝えればよい。 「ファイル名は日本語で」と頼むか、CLAUDE.md にその1行を書いておけば、以降は迷わず日本語で付けてくれる。

この「1つのことを1ファイルに書き、ディレクトリ一覧を眺めるだけで中身が分かるようファイル名に内容を入れる」というやり方は、ADR（Architecture Decision Record／意思決定記録）という既存の慣習から借りている。思いつきの命名ではない。

Architecture Decision Record（Martin Fowler）：「各記録はそれ自体が1ファイルであるべき」「ディレクトリ一覧で読めるよう、決定の内容をファイル名に入れる」
MADR（Markdown Any Decision Records）：Markdown 版の実装

ただし本家の ADR はファイル名の先頭を連番（0001-...）にする。ここで日付にしているのは、notes/ に入るのが決定だけでなく調査や下書きも含むから。番号で参照し合うことがないぶん、「いつ書いたか」のほうが手がかりになる。

3-3. 冒頭に「作成日」と「目的」、末尾に「## 参照」

# ログインキー方式の調査

- **作成日**: 2026-08-05
- **目的**: パスワードなしのログイン方式を比較して、どれを採用するか決める

## 調べたこと

パスキーは端末の生体認証で完結する（[Passkeys の解説](https://example.com/docs/passkey)）。

## 参照

- [Passkeys の解説](https://example.com/docs/passkey)

目的を1行書いておくと、後から読む自分もエージェントも、最初の3行で「このメモは何のためのものか」を判断できる。

出典は2か所に置く。 まず、その話が出てくる場所にリンクを直接置く。そのうえで末尾の ## 参照 に一覧としてまとめる（同じ出典を何度引いても1行）。裏を取り直すときや、調査を別のプロジェクトへ持っていくときに効くのは後者のほう。

末尾だけにしないのは、本文と出典の対応が黙って壊れるから。メモは何度も書き足され、節が並び替えられ、一部だけ切り出されて別の場所へ持っていかれる。そのたびに「どの主張がどの出典に支えられていたか」は、末尾のリストからは読み取れなくなる。Claude に読ませるときも、ファイル全体ではなく一部だけを読むことがあるので、離れた場所にある出典は視界に入らない。

これは古くからある話で、Wikipedia では text–source integrity と呼ばれている。AIエージェント向けでも同じ結論が出ていて、Google の OKF（→ §8）は「エージェントが文書を書き換え続けるので、並び順が変わった瞬間に黙って誤帰属する」という理由で、本文中に出典のラベルを置く形を規定している。

出典が多くて本文が読みにくくなるなら、GitHub の脚注記法 [^ラベル] を使ってもよい。そのときラベルは [^1] のような番号ではなく [^passkey-docs] のような語にする。番号だと、順番が変わったときに静かにずれる。

3-4. リンクは標準の Markdown 記法で書く

メモ同士をつなぐときは [表示テキスト](other-note.md) と書く。Obsidian でよく使う [[ファイル名]] は、GitHub 上ではただの文字列として表示されクリックできない。GitHub で読むことが前提なので、標準記法を使う。

4. GitHub がそのまま Wiki になる

in-repo 方式の分かりやすい利点がここ。何も設定しなくても、GitHub 上でメモが Wiki のように使える。GitHub Wiki 機能を有効にする必要すらない。

4-1. 何も設定せずにできること

ディレクトリを開くと README.md が表示される：GitHub で notes/ を開くと、その中に README.md があればファイル一覧の下に自動でレンダリングされる。索引を1枚置けば、それがそのまま notes/ のトップページになる（→ §7-1）
メモ同士のリンクがそのまま辿れる：.md をクリックすればレンダリングされた状態で表示され、[text](other-note.md) の相対リンクもそのままクリックして移動できる（→ MDB 9-2）。ページを行き来しながら読める、というのが Wiki らしさの正体
検索が効く：リポジトリページの検索窓から、メモの全文検索ができる。専用ツールの検索機能を覚える必要がない
履歴で「いつ考えが変わったか」が追える：コミット履歴を見れば、そのメモがいつどう書き換わったかが差分で分かる。「前はこう考えていたが、ここで方針を変えた」が残る。ノートアプリのメモ機能にはこれがない

4-2. ローカルで見るなら

レンダリングして読む方法は複数ある（→ MDB 9）。作業中に一番手間が少ないのは、Claudeデスクトップアプリの ビュー メニューから ファイル を開く方法（→ MDB 9-1）。Claude Code で書きながらそのまま確認できる。

5. AIエージェントに読み書きさせる

5-1. CLAUDE.md は短く保つ

CLAUDE.md に書くのは、毎回必ず守ってほしいルールだけ。数行で足りる。

## 作業メモ

調査・検討の経緯は notes/ に `<topic>-<YYYY-MM-DD>.md` の形式で置く。
冒頭に作成日と目的、末尾に「## 参照」を書く。
判断の背景を知りたいときは notes/ を読むこと。

判断の背景そのものは notes/ に置き、CLAUDE.md からは「知りたければ notes/ を見ろ」と指しておく。毎回読ませるものは短く、詳しい話は外のファイルに置く、という分担。

5-2. AGENTS.md を symlink にして Codex とも共有する

Claude Code は CLAUDE.md、Codex は AGENTS.md を自動で読む。両方に同じルールを効かせたいとき、AGENTS.md に「CLAUDE.md を参照すること」と書くだけでは弱い。Codex はその参照を自動では辿らないので、実際に読みに行くかどうかがそのときの判断任せになる。

確実なのは、symlink で実体を1つにする方法。

ln -s CLAUDE.md AGENTS.md

これで AGENTS.md は CLAUDE.md の別名になる。中身は常に一致し、二重メンテも要らない。git は symlink をそのまま追跡するので、clone しても関係は保たれる。

ただし Windows では注意が要る。Git の設定によっては symlink が本物のリンクにならず、「CLAUDE.md という文字列が1行入っただけのファイル」になることがある。Windows の人と共有するリポジトリでは、symlink をやめて2つのファイルの中身を揃える運用に切り替えるのが無難。

5-3. スキルを入れて任せる

ここまでの決めごとをスキルにまとめてある。入れておくと、「これ記録して」と一言頼むだけで、次を Claude が引き受ける。

置き場所を判断する：会話で答えるだけでよいのか、notes/ に1本書くのか、確定した方針として決定ログにも足すのか
ファイル名を付ける：<topic>-<YYYY-MM-DD>.md の形式で、内容が見分けられる名前にする
テンプレートに沿って書く：冒頭に作成日と目的、末尾に ## 参照
既存のメモを先に確認する：同じテーマのメモがあれば、新しく作らずそこに追記する
索引を更新する：notes/README.md があれば1行足す。手で運用していると一番忘れるところなので、ここが効く
無いものは作らない：DECISIONS.md や INBOX.md が無いリポジトリでは、その話を持ち出さない。使っていない仕組みを勝手に増やされない
リポジトリのルールを優先する：CLAUDE.md に別の指定があれば、スキルの既定よりそちらに従う

インストールは、Claudeデスクトップアプリならこの手順。

アカウントメニューから設定を開く
左メニュー「カスタマイズ」の プラグイン を開き、右上の追加 → マーケットプレイスを追加
リポジトリから追加 を選ぶ
URL 欄に yto/yto-skills を入れて同期
ディレクトリ 画面が開く。コード タブに yto-skills が現れる
In repo notes を選び、インストール

配る単位が「プラグイン」で、その中に「スキル」が入っている、という関係。今回はスキル1つだけのプラグインなので名前も同じだが、設定の「スキル」ではなく プラグイン から追加する。

ターミナル（Claude Code CLI）ならこの2行。

/plugin marketplace add yto/yto-skills
/plugin install in-repo-notes@yto-skills

/plugin はデスクトップアプリでは使えないので、そちらでは上の手順で入れる。

入れる前に中身を読む。スキルの正体は「Claude への指示文」で、入れるということは、書いた人の指示を自分のセッションに常駐させるということ。作者を知らないスキルを中身も見ずに入れるのは、知らない人が書いたスクリプトをそのまま実行するのと変わらない。ファイルを消す、秘密を外に送る、といった指示が混ざっていても気づけない。

このスキルは Markdown 1ファイルなので、そのまま読める：skills/in-repo-notes/SKILL.md。ざっと目を通して、納得できたら入れる。他の人が配っているスキルでも同じ。

6. 立ち上げる

6-1. スキルを入れている場合

一言でよい。

このリポジトリに作業メモの置き場所を作って。

notes/ が作られ、CLAUDE.md に数行のルールが足される。索引も決定ログも Inbox も、この時点では作られない（→ §7）。

6-2. スキルを使わない場合

やることは同じなので、プロンプトに直接書けばよい。

このリポジトリに作業メモの置き場所を作って。
notes/ フォルダを作り、CLAUDE.md に「調査や検討の経緯は notes/ に
<topic>-<YYYY-MM-DD>.md の形式で置く（topic は英数字とハイフン）。
冒頭に作成日と目的、末尾に参照を書く」というルールを追記して。

この場合、索引の更新やファイル名の付け方は自分で見ることになる。とくに notes/README.md を置いたあとの「メモを足したら索引も足す」は忘れやすいので、CLAUDE.md にその1行を書き足しておくとよい。

どちらの道でも、あとは調べものをするたびに「これ notes に残して」と頼むだけ。

7. 使いながら育てる

最初から全部そろえない。notes/ で回してみて、足りなくなったところだけ足していく。足せるものは3つあるが、必要になるタイミングがそれぞれ違うので、要るものだけでよい。

7-1. notes/README.md：ノートが増えたら索引を置く

きっかけは、ファイル名だけでは中身が分からなくなったとき。目安は20本を超えたあたり。

notes/README.md に「ファイル名と1〜2文の概要」を1行ずつ並べる。GitHub で notes/ を開いたときに自動で表示されるので（→ §4-1）、これがそのまま目次になる。

# notes/ 索引

- [login-key-research-2026-08-05.md](login-key-research-2026-08-05.md)
  パスワードなしのログイン方式の比較。パスキー採用の根拠
- [d1-vs-kv-2026-08-01.md](d1-vs-kv-2026-08-01.md)
  D1 と KV の使い分け。検索が要るなら D1

7-2. DECISIONS.md：決定だけを追えるようにする

きっかけは、「今の方針は何で、なぜそうなったか」を素早く知りたくなったとき。とくに、しばらく間が空いたプロジェクトに戻るときに効く。

リポジトリのルートに DECISIONS.md を1枚置き、確定した方針だけを日付順に追記する。詳細は書かず、notes/ のメモへリンクする。

# DECISIONS

- **2026-08-05：ログイン方式はパスキーを採用**（メールアドレスを持たずに済み、端末の生体認証で完結するため）[login-key-research](notes/login-key-research-2026-08-05.md)
- **2026-08-01：データベースは D1 を使う**（投稿の検索が要るため。KV では絞り込みができない）[d1-vs-kv](notes/d1-vs-kv-2026-08-01.md)

書き換えずに追記だけしていくのがポイント。方針を撤回したときも、古い行は消さずに「〔撤回〕」と印を付けて残し、新しい行を足す。いつ考えが変わったかが読めることに価値があるので、履歴を消してはいけない。

7-3. notes/INBOX.md：思いつきを捕捉する

きっかけは、「後で調べたい」が溜まるのに、そのたびファイルを作るのが面倒なとき。

notes/INBOX.md を1枚置いて、1行ずつ追記するだけ。分類もタグ付けもしない。

- 2026-08-05 Workers AI の料金、他社と比較したい
- 2026-08-06 https://example.com/ 後で読む

ちゃんと調べる価値が出てきたら、正式なメモに起こして Inbox の行は消す。捨ててよいのが Inbox の性質なので、溜まったら遠慮なく消す。

7-4. 索引を2つ持つときは、肥大させない

notes/README.md と DECISIONS.md は、どちらも notes/ のメモにリンクするので似て見える。ただし索引している対象が違う。

	notes/README.md	DECISIONS.md
索引しているもの	ファイル	決定
載るもの	全部のメモ（調査だけ、ボツも）	確定した方針だけ
更新のしかた	上書きして現在の一覧を保つ	追記のみ。撤回も残す
読む動機	「あのメモどこだっけ」	「今の方針と、その理由」

1つのメモから決定が2つ出ることもあれば、メモを持たない決定もある。片方にもう片方を畳もうとすると、どちらかが壊れる。README に畳めば撤回の履歴が消え、DECISIONS に畳めば「決定に至らなかった調査」が索引から消える。

そのうえで注意。どちらも肥大させない。索引に説明を書き込みすぎると、メモ本体と同じことを2箇所に書くことになり、分けた意味が消える。README の概要は1〜2文、DECISIONS.md は結論と根拠の要点まで。詳細は必ずメモ本体に書いてリンクする。

7-5. 育てたあとの運用はスキルが引き受ける

足すかどうかを決めるのは自分で、スキルが勝手に作ることはない。ただし置いたあとの手間はスキルが持っていく（→ §5-3）。

notes/README.md を置けば、ノートを書くたびに索引へ1行足す
DECISIONS.md を置けば、方針が確定したときだけ1行追記する
notes/INBOX.md を置けば、1行の捕捉と、正式なノートへ昇格したときの行の削除をする

スキルは起動のたびにこの3つの有無を見るので、置いた瞬間から扱いが切り替わる。設定を書き換える必要はない。自分で覚えておくのは「そろそろ足すか」の判断だけでよくなる。

8. 補足：ほかのやり方との違い

「Claude のメモリ機能ではだめなのか」「それ Obsidian でやることでは」「Google が OKF という仕様を出したはず」と思った人向け。3つ並べるが、結論としてはどれとも対立していない。

ツール組み込みのメモリ機能との違い

Claude Code にも Codex にも、セッションをまたいで記憶を持つ機能がある。便利だが、in-repo 方式とは向きが逆になる。

	ツール組み込みのメモリ	in-repo
置き場所	ホームディレクトリの下（リポジトリの外）	リポジトリの中
git に乗るか	乗らない	乗る
別のマシン	付いてこない	clone すれば付いてくる
他のエージェント	読めない	読める

置き場所は、Claude Code が ~/.claude/ の下、Codex が ~/.codex/memories/（2026-08 時点）。どちらもリポジトリの外なので、プロジェクトを clone しても記憶は付いてこないし、相手のエージェントからは見えない。「clone すれば経緯ごと手に入る」という利点と正面からぶつかる。

ただし「移せない」わけではない。中身はファイルなので、書き出して別のところへ移すことはできる。効いてくるのは同時に使うとき。Claude Code と Codex を並行して回すなら、どちらに書いても片方からは見えないので、記憶を同期し続ける仕掛けを自分で用意することになる。in-repo なら置き場所がそもそも1つなので、同期という問題が発生しない。同期の仕組みを考えるより、最初から1か所に置くほうが手軽、というのが選んだ理由。

とはいえツール組み込みのメモリを捨てる必要はなく、住み分けの問題。リポジトリに紐づかない個人の好み（「push は指示があるまで待つ」など）はツール組み込みのメモリに置き、プロジェクトの知識は in-repo に置く。

Obsidian との違い

Obsidian は知識管理ツール。in-repo 方式に無くて Obsidian にあるものは、主に人間が知識を眺め、編むための機能。

Obsidian の機能	in-repo での代わり
バックリンク（このメモを参照している他のメモの一覧）	検索
グラフビュー（メモ同士の関係を図で表示）	なし
リンクのリネーム追従	なし（下記の弱点）
Dataview（frontmatter を動的に集計）	索引を手で書く
タグでの絞り込み	検索

並べると見劣りするが、主役がAIエージェントだと意味が変わる。バックリンクもグラフも、ファイルを横断して読めるエージェントには必須ではない。その代わりに in-repo は、git の版管理・clone での可搬性・エージェント非依存を取っている。要はトレードで、どちらが上という話ではない。

そのうえで、実際に効く弱点は2つある。

リンクが腐る：ファイル名を変えると、他のメモから張ったリンクが静かに切れる。対策は「リネームしない」。どうしても変えるなら、変更後に古いファイル名で検索して張り替える
索引が手で古くなる：README.md の索引は自動更新されない。「メモを足したら索引も足す」をルールにするしかない。スキルに任せるのが確実

逆に Obsidian 側にも弱点はある。[[wikilink]] や埋め込み、Dataview のクエリを使うほど、ファイルが Obsidian 前提の形になっていく。GitHub や静的サイトで使おうとすると手直しが要る。

そして逃げ道がある。notes/ の中身はただの .md なので、バックリンクやグラフが欲しくなったら、そのまま Obsidian の vault として開けばよい。移行のコストはほぼゼロ。「今は持たないが、いつでも持てる」というのが、この比較でのいちばん強い答え。

Google OKF との違い

OKF（Open Knowledge Format）は、2026年に Google Cloud が公開した知識のファイル形式の仕様。ツールでもサービスでもなく、実体は「YAML frontmatter 付きの Markdown を集めたディレクトリ」。必須項目は frontmatter の type ただ1つ。

土台の思想は in-repo 方式とほぼ同じ結論に着地している。素の Markdown で書く、git を推奨する、特定のベンダーに縛られない、リンクは標準の Markdown 記法を使う。新しい形式を作らず、すでに誰でも読める形に寄せる、という立場も同じ。

違うのは想定している書き手。OKF は「エージェントが大量に生成し続ける知識」を前提にしていて、その知識が何から作られたか、誰が検証したか、いつ古くなるかを frontmatter で表明する仕組みを持つ。個人が数十本のメモを書く規模では、そこまでの装備は要らない（git の履歴と目視で足りる）。

学べる点を1つ挙げるなら、いつ古くなるかを書いておくという発想。価格やUI手順のように腐りやすい情報を含むメモには、「この情報は2026-08 時点」と冒頭に書いておくと、後から読んだときの扱いが決めやすい。

2026-08-09 タツヲ (yto)

☕️ Vibecoding Notes を応援