作業メモと決定をリポジトリの中に残す：AIと共有する in-repo 方式
Claude Code と作業していると、「なぜこの方式にしたのか」「あのとき何を調べたのか」がどんどん積み上がる。それをどこに置くか、という話。
「これ覚えておいて」と頼むと、Claude は行き先を自分で決める。多くはリポジトリの外の見えない場所で、古くなっても気づかない（→ §7）。そうならないための解決策を紹介する。
結論は単純で、作業しているリポジトリの中に Markdown で置く。専用のツールもサービスも要らない。GitHub に置けば、そのまま Wiki のように読める。
1. in-repo 方式でやること
Section titled “1. in-repo 方式でやること”in-repo 方式：調査メモや知見を、専用ツールではなく対象リポジトリの中に素の Markdown で置き、git で版管理し、AIエージェントが直接読み書きするやり方。
in-repo 方式と名前を付けてはいるが、発明でも独自手法でもない。リポジトリの中に Markdown を置いて git で管理する、というだけのことで、多くの開発者が名前を意識せずに同じことをやっている。毎回長い説明を書かずに済ませるための呼び名。
やることも1つで、行き先を自分で決めるだけ。毎回読ませるルールは CLAUDE.md、判断の経緯は notes/。どちらもリポジトリの中に置く（→ §3）。行き先が決まるので散らばらず、2つに分けるので CLAUDE.md が肥大化しない。
そのうえで、置き場所をリポジトリの中にしたことで得られるものが4つある。
- 自分の目に入る：プロジェクトを開けばそこにある。Finder でも GitHub でも一覧でき、コミットのたびに視界を通る（→ §8）
- どのエージェントからも読める：Claude Code でも Codex でも、ただのファイルなので普通に読める
- clone すれば記憶も付いてくる：別のマシンに移っても、そのまま手に入る
- git の履歴が残る：いつ考えが変わったかが後から追える
1-1. 決めごとは Claude に引き受けてもらう
Section titled “1-1. 決めごとは Claude に引き受けてもらう”置き場所の判断からファイル名・索引の更新まで、この方式の手間は Claude 側に渡せる。決めごとを書いたファイルを1つ置いておけば（→ §2-1）、「これ記録して」と一言頼むだけで、後はやってくれる。
- 置き場所を判断する：会話で答えるだけでよいのか、
notes/に1本書くのか、確定した方針として決定ログにも足すのか - ファイル名を付ける：
<topic>-<YYYY-MM-DD>.mdの形式で、内容が見分けられる名前にする - テンプレートに沿って書く：冒頭に作成日と目的、末尾に
## 参照 - 既存のメモを先に確認する：同じテーマのメモがあれば、新しく作らずそこに追記する
- 索引を更新する：
notes/README.mdがあれば1行足す。手で運用していると一番忘れるところなので、これは有効 - 無いものは作らない：
DECISIONS.mdやINBOX.mdが無いリポジトリでは、その話を持ち出さない。使っていない仕組みを勝手に増やされない - リポジトリのルールを優先する：
CLAUDE.mdに別の指定があれば、決めごとの既定よりそちらに従う
これは道具の話なので、無くても同じことは手でできる（→ §2-3）。合わなければファイルを消せば元どおりで、後に何も残らない。置き方は次の §2 に2通り書いてある。
1-2. 置き場所は作業フォルダ。GitHub が最終の保管先
Section titled “1-2. 置き場所は作業フォルダ。GitHub が最終の保管先”メモが生まれて読み書きされるのは、いま作業しているフォルダ（＝リポジトリ）の中。まずはそれだけでいい。プロジェクトを開けばそこにあって、AIも自分もすぐ読める。
git で管理すれば、そこにドキュメントの履歴が乗る。いつ考えが変わったかが差分で残る。
そのうえで GitHub に push しておくと、そこが最終の保管先になる。手元のフォルダが消えても残り、ブラウザだけで読めて検索でき、別のマシンからも clone で取れる（→ GBA）。段階でいうとこう。
- 作業フォルダに置くだけ：それでもAIは読むし、自分の目にも入る。経緯が1か所に集まる
- git で管理する：いつ考えが変わったかが履歴に残る
- GitHub に push する：上に加えて、控えが残り、ブラウザで読めて検索でき、別マシンでも手に入る（→ §8）
一番上（置くだけ）でも、目に見えて自分の手で管理できるという望みは満たされている。どこに置くかより、notes/ を作るほうが先。GitHub に上げるのは、notes/ が育ってからでも遅くない。
GitHub に置くなら、リポジトリは Private にしておくのがおすすめ。記事やアプリのコードと違って、メモは書くときに公開を意識しない。公開前のURL、どのアカウントで認証しているか、人の名前、ボツにした案。そういうものが自然と混ざる。後から Public に切り替えるのは簡単だが、逆は履歴が残るので取り返しがつかない（→ GBA 6-2）。
2. 立ち上げる
Section titled “2. 立ち上げる”入れ方は2つある。先に見るのは 2-1 でよい。
- ルールノート（→ §2-1）：決めごとを書いたファイルを
notes/に1つ置くだけ。作業フォルダの外に何も残らず、Codex など他のエージェントからも読める - スキル（→ §2-2）：Claude Code の仕組みとして入れる。一度入れれば、どのフォルダで作業していても効く
置く前に中身を読む。ルールノートもスキルも、正体は「Claude への指示文」。置くということは、書いた人の指示を自分の Claude に読ませるということ。作者を知らないものを中身も見ずに使うのは、知らない人が書いたスクリプトをそのまま実行するのと変わらない。ファイルを消す、秘密を外に送る、といった指示が混ざっていても気づけない。
どちらも Markdown 1ファイルなので、そのまま読める。全文は §10 に載せてあるほか、GitHub でも読める。細かく読み込まなくてよいが、何をさせるものかは見ておく。他の人が配っているものでも同じ。
2-1. ルールノートを置く
Section titled “2-1. ルールノートを置く”決めごとを書いたファイルを notes/ に置き、CLAUDE.md からそれを指す。置くファイルは1つだけ。
このフォルダに作業メモの置き場所を作って。決めごとはhttps://raw.githubusercontent.com/yto/yto-skills/main/plugins/in-repo-notes/skills/in-repo-notes/SKILL.mdを notes/rules-in-repo-notes.md として保存して、CLAUDE.md からそれを読むように書いて。こうなる。
myproject/ CLAUDE.md notes/ rules-in-repo-notes.md ← 決めごと（ルールノート）CLAUDE.md に入るのは数行だけ。
## 作業メモ
調査・検討の経緯は notes/ に残す。書き方の決めごとは notes/rules-in-repo-notes.md にあるので、記録を頼まれたらそれに従う。中身は付録にそのまま載せてある（→ §10）。上のプロンプトを使わず、コピーして貼ってもよい。
この方式の利点は3つ。
- 作業フォルダの外に何も残らない：フォルダを消せば何も残らない。他のフォルダでの作業にも影響しない
- どのエージェントからも読める：
AGENTS.mdをCLAUDE.mdへの symlink にしておけば、Codex も同じものを読む（→ §8-3） - 中身が見えている：ただのファイルなので、いつでも開いて読めるし、気に入らなければ書き換えられる
Claude Code には
.claude/rules/という似た仕組みもある。ただしあれは Claude Code 専用。ここで置くのはnotes/の中のただのファイルなので、他のエージェントからも読める。
2-2. スキルとして入れる
Section titled “2-2. スキルとして入れる”Claude Code のスキルとして入れる方法もある。一度入れれば、どのフォルダで作業していても効くのが違い。
Claudeデスクトップアプリならこの手順。
- アカウントメニューから 設定 を開く
- 左メニュー「カスタマイズ」の プラグイン を開き、右上の 追加 → マーケットプレイスを追加
- URL 欄に
yto/yto-skillsを入れて 同期
①設定の プラグイン → ②右上の 追加 → マーケットプレイスを追加 → ③URL 欄にリポジトリ名 → ④同期（画像は例。実際には yto/yto-skills と入れる）
- ダイアログを閉じ、探索 タブを開く
- In repo notes の 追加 を押す
探索 タブに並ぶので、右の 追加 を押す（画像は例）
配る単位が「プラグイン」で、その中に「スキル」が入っている、という関係。今回はスキル1つだけのプラグインなので名前も同じだが、設定の「スキル」ではなく プラグイン から追加する。
ターミナル（Claude Code CLI）ならこの2行。
/plugin marketplace add yto/yto-skills/plugin install in-repo-notes@yto-skills/plugin はデスクトップアプリでは使えないので、そちらでは上の手順で入れる。
それでも進めないときは、無理に探さず §2-1 のルールノートにする。 できることは同じ。
2-3. どちらでも、あとは頼むだけ
Section titled “2-3. どちらでも、あとは頼むだけ”ルールノートでもスキルでも、立ち上げたあとは一言でよい。
このフォルダに作業メモの置き場所を作って。notes/ が作られ、CLAUDE.md に数行のルールが足される。索引も決定ログも Inbox も、この時点では作られない（→ §6）。
どちらも使わない方法もある。やることは同じなので、プロンプトに直接書けばよい。
このフォルダに作業メモの置き場所を作って。notes/ フォルダを作り、CLAUDE.md に「調査や検討の経緯は notes/ に<topic>-<YYYY-MM-DD>.md の形式で置く（topic は英数字とハイフン）。冒頭に作成日と目的、末尾に参照を書く」というルールを追記して。この場合、索引の更新やファイル名の付け方は自分で見ることになる。とくに notes/README.md を置いたあとの「メモを足したら索引も足す」は忘れやすいので、CLAUDE.md にその1行を書き足しておくとよい。
どの方法でも、あとは調べものをするたびに「これ notes に残して」と頼むだけ。
3. まず notes/ ひとつから始める
Section titled “3. まず notes/ ひとつから始める”3-1. 1つのプロジェクトは1つのフォルダに
Section titled “3-1. 1つのプロジェクトは1つのフォルダに”前提として、1つのプロジェクトは1つのフォルダにまとめておく。ブログと家計簿アプリと仕事の資料を1つのフォルダに入れて Claude を起動すると、そのすべてが視界に入る。
これは Claude Code の作りに沿った話で、どこで起動したかが、読み書きできるファイルの範囲と、読み込まれる CLAUDE.md を決める。範囲が広いほど関係のないものがコンテキストに入り、埋まるほど Claude は前の指示を忘れたり間違えたりしやすくなる（→ 大規模コードベースのガイド）。無関係な作業を1つに混ぜた状態には「kitchen sink（なんでも入り）」という呼び名も付いている（→ ベストプラクティス）。
混ざるのはファイルだけではない。CLAUDE.md も1枚になるので、ブログのルールと家計簿のルールが同居する。同じページに「肥大した CLAUDE.md は Claude に本来の指示を無視させる」「矛盾するルールが2つあると、どちらかを勝手に選ぶ」とある。さらに Claude が自分で書く記憶は git リポジトリを単位として置かれるので（→ §9）、混ぜたフォルダは丸ごと1つのプロジェクトとして扱われる。分けて置いたはずのメモも、混ざってしまう。
3-2. 最初の構成
Section titled “3-2. 最初の構成”最初の構成はこんな感じになる。
myproject/ CLAUDE.md notes/ d1-vs-kv-2026-08-01.md login-key-research-2026-08-05.md （以下、アプリのファイル）CLAUDE.md：毎回読ませるルール。短く保つnotes/：経緯そのもの。調査・計画・下書き・ボツ案。長くてよい
分担は「毎回読ませるものは短く CLAUDE.md へ、詳しい話は notes/ へ」。CLAUDE.md に判断の背景まで書くと、肝心のルールがその中に埋もれる。
使い方は、調べものをしたあとに一言頼むだけ。
いま調べた内容を notes/ にメモとして残して。4. メモを挟みながら開発する
Section titled “4. メモを挟みながら開発する”notes/ が用意できたら、あとは使うだけ。ここでは、こちらが打つプロンプトだけを順に並べる。実際に手を動かす必要はなく、流れを見るための例。使う道具は notes/ フォルダひとつだけで、決定ログも索引も出てこない。
4-1. 読書記録アプリを作る（架空の例）
Section titled “4-1. 読書記録アプリを作る（架空の例）”読書記録アプリを1本作るとして、どんな順で頼むことになるか。
このアプリは実在しない。 これまで実際にやってきた進め方をもとに組み立てた例で、アプリもファイル名も日付も作りもの。そして Claude は、同じように頼んでも毎回同じようには動かない。 人によっても、そのときによっても、返ってくるものは変わる。ここで見てほしいのは個々の応答ではなく、メモを挟みながら進むという形のほう。
1. 作る前に調べる
読書記録アプリを作りたい。似たサービスがどんな機能を持っているか調べて、notes にまとめて。→ notes/competitor-research-2026-07-01.md
2. 調べたメモを見て、作るものを絞る
さっきのメモを見て、最初に作る機能を3つに絞りたい。相談にのって。決めたことと、今回やらないことを、同じメモに書き足しておいて。→ 同じファイルに「決めたこと」「今回やらないこと」の節が増える
3. こちらから条件を出して、やり方を決める
機能を絞るなかで、ユーザー登録が要るという話になったとする。ここで作り手の側から条件を出す。
ユーザー登録が要りそうだけど、メールアドレスは個人情報なので自分では管理しきれない。なるべく預かりたくない。メールアドレスを使わないログインのやり方を調べて。→ 調べた結果がメモになる
ソーシャルログイン方式にする。PCでもスマホでも使うとするとこれがよい。メモしといて。→ 同じメモに「決めた方式」と「採らなかった案とその理由」が並ぶ
メールアドレスを使わない認証には、ソーシャルログイン（→ SOL）、ログインキー方式（→ LKA）、パスキー（→ PKA）がある。
4. やりたい機能を調べて、いったん見送る
3 が「どうやるか」の選択なら、こちらは「やるかやらないか」の選択。
本の写真を撮ったら、AIが表紙から書名を読み取って登録してくれる機能を入れたい。ただ実装が大変そうだし、お金もかかりそう。実現できるか、いくらくらいかかるか、いいところと悪いところを調べてnotes にまとめて。→ notes/photo-recognition-2026-07-02.md
調べた結果を読んでから、こちらが決める。
やっぱり今の段階では見送る。本のバーコードを写真で撮れば情報を取れるかな？→ 同じメモの末尾に、こういう節が入る
## 今回は見送る（2026-07-02 追記）
写真から書名を読む部分は実現できるが、1枚あたり数円かかる。本を登録するたびに課金が発生する状態は避けたい。手入力なら0円で、登録する冊数もそう多くない。
**再検討の条件：料金が下がったとき、または手入力が実際に苦になったとき。**
**代案：裏表紙の ISBN バーコードなら、AI を使わずに読める。** 書名もそこから引けるので、こちらを先に試す。伝えるのは判断だけでよい。調べた中身はすでにメモにあるので、理由は Claude が補って書く。見送って終わりにもしない。 その場で浮かんだ代案を一言足しておけば、それも同じメモに残る。
5. 作らせる前に、名前を決める
名前を決めたい。案を3つくらい出して。条件は2つ。ドメインが空いていること。最初に調べた競合と紛らわしくないこと。調べた結果を notes に残して。→ notes/naming-2026-07-02.md
候補とドメインの空き状況が並ぶ。
一番目のにする。短くて覚えやすいし、わかりやすい。ドメインも取るけど、それは後でいい。決めた理由も残しておいて。→ 同じメモに決定が入る。「ドメインは後で取る」も残るので、あとで「そういえば取っていなかった」と気づける
6. メモに書いた方針どおりに作らせる
さっきのメモに書いた方針どおりに作って。認証の実装はあとまわしで。→ ここで初めてアプリのコードができる。作るものも決めた方式もメモにあるので、その場で足すのは順番の指示だけで済む
認証はこの後で足す。先に動くものを見たいから順番を変えただけで、決めた方式は 3 のメモに残っているので、戻ってきたときに調べ直さずに済む。
7. 作ってから、デザインを考え直す
見た目がありきたり。もう少し個性を出したい。読書に合う世界観を4つくらい考えて、それぞれのデザインを確認させて。森の中、都会のカフェ、図書館、学校の教室、みたいな方向で。→ 候補が並ぶ。ここは読んで決めるのではなく、見て決める
図書館で行こうと思います。森だとちょっと狙いすぎ感もあるし、カフェはおしゃれすぎるし、学校はノスタルジーすぎる。自分の世界観に合うのは図書館だな。選んだ理由と、選ばなかった案も notes に残しておいて。→ notes/design-direction-2026-07-15.md
8. 公開したあとのことを考える
どう広めるか考えたい。プランを notes にまとめて。→ notes/launch-plan-2026-07-20.md
プランに SNS がよさそうだとあったので、そのまま続けて頼む。
各種SNSへの告知の文面を考えて、さっきのメモに足しておいて。→ 同じメモに、媒体ごとの文面案が並ぶ。投稿するときはここからコピーする
9. 1か月後、自分で蒸し返す
やはり表紙画像の写真から登録するやつも入れたいな。もう一度調べてみて。→ 4 のメモが読まれる。見送った理由と「再検討の条件」が返ってくるので、料金は下がったかと突き合わせて決められる。ゼロから調べ直さずに済む
10. 2か月後、人から勧められる
「メールで通知を送れば？」と言われたんだけど、どうだったっけ。→ 3 のメモが読まれ、メールアドレスを預からないと決めた理由が返ってくる
4-2. この流れで起きていること
Section titled “4-2. この流れで起きていること”メモが、次の指示の材料になっている。 2 で「さっきのメモを見て」、6 で「メモに書いた方針どおり」と言えるのは、1 から 5 の結果がファイルとして残っているから。書きっぱなしにはならず、調べた結果がそのまま次の作業の入力になる。
条件を出すのは作り手のほう。 3 の「メールアドレスは預かりたくない」も、4 の「お金がかかるなら今はやらない」も、7 の「森だと狙いすぎ、カフェはおしゃれすぎる」も、Claude が言い出したことではない。調べれば分かることは後からでも調べ直せるが、自分の言葉で言ったことは、その場で書き留めないと戻ってこない。
やらない決定が3種類ある。 3 は「やるが、この方式は採らない」、4 は「そもそも今はやらない」、7 は「この見た目にはしない」。どれも、選ばなかったものが理由つきで残る。作ったものだけ記録していると、全部消える。4 では「再検討の条件」まで書いてあるので、9 でそのまま突き合わせられる。
計画ファイル1枚には収まらない話がある。 4 と 5 がそれ。名前の検討もドメインの空き状況も、実装の段取りではないので計画書には書かない。それでも、しばらく経てば必ず参照したくなる。テーマごとにファイルが増えるほうが、この手の話を捨てずに済む。
コードを書かない仕事のほうが多い。 10ステップのうち、コードが出てくるのは 6 と 7 だけ。残りは調べる・決める・書き留める。ここは開発の記録であって、コードの記録ではない（→ §7）。
5. 書き方の決めごと
Section titled “5. 書き方の決めごと”決めごとはシンプルに4つだけ。
しかも、この4つを自分で覚えて守る必要はない。CLAUDE.md に書くか、スキルを入れておけば、ファイル名を付けるのも索引を更新するのも Claude がやる（→ §1-1）。この章は何を任せることになるのかを確認するための記録。中身を知らないままだと、出てきたファイル名や構成が自分に合っているかを判断できなくなる。
5-1. 1テーマ1ファイル、フラットに置く
Section titled “5-1. 1テーマ1ファイル、フラットに置く”サブフォルダは作らない。テーマ別に分けたくなるが、「どの階層に入れるか」を毎回考えるコストのほうが高い。ファイルが増えて一覧しづらくなったら、フォルダを増やすのではなく索引で吸収する（→ §6-1）。
5-2. ファイル名は <topic>-<YYYY-MM-DD>.md
Section titled “5-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.md にその1行を書いておけば、以降は迷わず日本語で付けてくれる。
この「1つのことを1ファイルに書き、フォルダ一覧を眺めるだけで中身が分かるようファイル名に内容を入れる」というやり方は、ADR（Architecture Decision Record／意思決定記録）という既存の慣習から借りている。
- Architecture Decision Record（Martin Fowler）：「各記録はそれ自体が1ファイルであるべき」「フォルダ一覧で読めるよう、決定の内容をファイル名に入れる」
- MADR（Markdown Any Decision Records）：Markdown 版の実装
ただし本家の ADR はファイル名の先頭を連番（0001-...）にする。ここで日付にしているのは、notes/ に入るのが決定だけでなく調査や下書きも含むから。番号で参照し合うことがないぶん、「いつ書いたか」のほうが手がかりになる。
5-3. 冒頭に「作成日」と「目的」、末尾に「## 参照」
Section titled “5-3. 冒頭に「作成日」と「目的」、末尾に「## 参照」”# ログインキー方式の調査
- **作成日**: 2026-08-05- **目的**: パスワードなしのログイン方式を比較して、どれを採用するか決める
## 調べたこと
パスキーは端末の生体認証で完結する（[Passkeys の解説](https://example.com/docs/passkey)）。
## 参照
- [Passkeys の解説](https://example.com/docs/passkey)この形（作成日・目的・末尾の参照）も、スキルを入れていれば Claude が自動で整える（→ §1-1）。
目的を1行書いておくと、後から読む自分もエージェントも、最初の3行で「このメモは何のためのものか」を判断できる。
出典は2か所に置く。 まず、その話が出てくる場所にリンクを直接置く。そのうえで末尾の ## 参照 に一覧としてまとめる（同じ出典を何度引いても1行）。裏を取り直すときや、調査を別のプロジェクトへ持っていくときに使うのは後者のほう。
末尾だけにしないのは、本文と出典の対応がいつの間にか壊れるから。メモは何度も書き足され、節が並び替えられ、一部だけ切り出されて別の場所へ持っていかれる。そのたびに「どの主張がどの出典に支えられていたか」は、末尾のリストからは読み取れなくなる。Claude に読ませるときも、ファイル全体ではなく一部だけを読むことがあるので、離れた場所にある出典は視界に入らない。
これは古くからある話で、Wikipedia では text–source integrity と呼ばれている。AIエージェント向けでも同じ結論が出ていて、Google の OKF（→ §9）は「エージェントが文書を書き換え続けるので、並び順が変わった瞬間に黙って誤帰属する」という理由で、本文中に出典のラベルを置く形を規定している。
出典が多くて本文が読みにくくなるなら、GitHub の脚注記法 [^ラベル] を使ってもよい。そのときラベルは [^1] のような番号ではなく [^passkey-docs] のような語にする。番号だと、順番が変わったときに静かにずれる。
5-4. リンクは標準の Markdown 記法で書く
Section titled “5-4. リンクは標準の Markdown 記法で書く”メモ同士をつなぐときは [表示テキスト](other-note.md) と書く。Obsidian でよく使う [[ファイル名]] は、GitHub 上ではただの文字列として表示されクリックできない。GitHub で読むことが前提なので、標準記法を使う。
6. 使いながら育てる
Section titled “6. 使いながら育てる”最初から全部そろえない。notes/ で回してみて、足りなくなったところだけ足していく。足せるものは3つあるが、必要になるタイミングがそれぞれ違うので、要るものだけでよい。
6-1. notes/README.md：ノートが増えたら索引を置く
Section titled “6-1. notes/README.md：ノートが増えたら索引を置く”きっかけは、ファイル名だけでは中身が分からなくなったとき。目安は20本を超えたあたり。こう頼む。
notes/ の索引を作って。notes/README.md に「ファイル名と1〜2文の概要」が1行ずつ並ぶ。GitHub で notes/ を開いたときに自動で表示されるので（→ §8-1）、これがそのまま目次になる。スキルを入れていれば、以降はメモを足すたびに索引も自動で更新される（→ §6-5）。
# 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索引は、AI のコンテキストを節約する装置でもある。notes/ は起動時にまとめて読み込まれるわけではない（毎回まるごと読まれるのは CLAUDE.md だけ → §3-2）。Claude は必要になったときだけ、索引を数十行見て関係する1本を開く。だから何本たまっても、セッションのコンテキストは開いたぶんしか増えない。索引が無くても、ファイル名（<topic>-<日付> → §5-2）や検索で狙い読みできるので「全部読む」にはならないが、索引に1〜2文の要約があると、ファイル名だけでは絞れないときの命中率が上がる。
6-2. DECISIONS.md：決定だけを追えるようにする
Section titled “6-2. DECISIONS.md：決定だけを追えるようにする”きっかけは、「今の方針は何で、なぜそうなったか」を素早く知りたくなったとき。とくに、しばらく間が空いたプロジェクトに戻るとき。こう頼む。
確定した方針だけを追える 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)書き換えずに追記だけしていくのがポイント。方針を撤回したときも、古い行は消さずに「〔撤回〕」と印を付けて残し、新しい行を足す。いつ考えが変わったかが読めることに価値があるので、履歴を消してはいけない。
6-3. notes/INBOX.md：思いつきを捕捉する
Section titled “6-3. notes/INBOX.md：思いつきを捕捉する”きっかけは、「後で調べたい」が溜まるのに、そのたびファイルを作るのが面倒なとき。こう頼む。
あとで調べたいことを1行ずつ溜める notes/INBOX.md を作って。notes/INBOX.md を1枚置いて、1行ずつ追記するだけ。分類もタグ付けもしない。
- 2026-08-05 Workers AI の料金、他社と比較したい- 2026-08-06 https://example.com/ 後で読む頼むときのコツは、その場で調べさせないこと。「調べたい」とだけ言うと、そのまま調べ始めることがある。
Workers AI の料金が他社と比べてどうか、あとで調べたい。いまは調べなくていいので、INBOX に1行だけ足しておいて。ちゃんと調べる価値が出てきたら、正式なメモに起こして Inbox の行は消す。
INBOX の Workers AI の料金の件、いま調べて notes にメモとして起こして。終わったら INBOX の行は消して。捨ててよいのが Inbox の性質なので、溜まったら遠慮なく消す。
6-4. 索引を2つ持つときは、肥大させない
Section titled “6-4. 索引を2つ持つときは、肥大させない”notes/README.md と DECISIONS.md は、どちらも notes/ のメモにリンクするので似て見える。ただし索引している対象が違う。
| notes/README.md | DECISIONS.md | |
|---|---|---|
| 索引しているもの | ファイル | 決定 |
| 載るもの | 全部のメモ（調査だけ、ボツも） | 確定した方針だけ |
| 更新のしかた | 上書きして現在の一覧を保つ | 追記のみ。撤回も残す |
| 読む動機 | 「あのメモどこだっけ」 | 「今の方針と、その理由」 |
1つのメモから決定が2つ出ることもあれば、メモを持たない決定もある。片方にもう片方を畳もうとすると、どちらかが壊れる。README に畳めば撤回の履歴が消え、DECISIONS に畳めば「決定に至らなかった調査」が索引から消える。
そのうえで注意。どちらも肥大させない。索引に説明を書き込みすぎると、メモ本体と同じことを2箇所に書くことになり、分けた意味が消える。README の概要は1〜2文、DECISIONS.md は結論と根拠の要点まで。詳細は必ずメモ本体に書いてリンクする。
6-5. 育てたあとの運用はスキルが引き受ける
Section titled “6-5. 育てたあとの運用はスキルが引き受ける”足すかどうかを決めるのは自分で、スキルが勝手に作ることはない。ただし置いたあとの手間はスキルが持っていく（→ §1-1）。
notes/README.mdを置けば、ノートを書くたびに索引へ1行足すDECISIONS.mdを置けば、方針が確定したときだけ1行追記するnotes/INBOX.mdを置けば、1行の捕捉と、正式なノートへ昇格したときの行の削除をする
スキルは起動のたびにこの3つの有無を見るので、置いた瞬間から扱いが切り替わる。設定を書き換える必要はない。自分で覚えておくのは「そろそろ足すか」の判断だけでよくなる。
7. そもそもなぜ in-repo なのか
Section titled “7. そもそもなぜ in-repo なのか”ここまでの方式を選んだ理由。もともとの困りごとはこれ。
まず困るのは、セッションをまたぐと経緯が消えること。新しいセッションの Claude は、前回どんな案を検討して何を捨てたかを知らない。同じ調査をもう一度させることになる。
そこで「これ覚えておいて」と頼む。ここで問題になるのが、行き先を指定しないと Claude が自分で決めてしまうこと。行き先はだいたい2つに分かれる。
CLAUDE.mdに書かれる：以後のルールとして書かれることが多い。ただし判断の背景まで書き込むと膨らむ。常駐の指示ファイルは毎回読み込まれるので、肥大化させるほど1回あたりのコストが上がり、肝心のルールが埋もれる- ツール組み込みのメモリ機能に書かれる：事実や経緯として書かれることが多い。置き場所はリポジトリの外になる（→ §9）
後者では、2つのことが同時に起きる。1つは、Claude Code と Codex で置き場所が別なので、片方に貯めたものはもう片方から見えないこと。もう1つは、自分からも見えなくなること。Claude Code なら隠しフォルダの下に、パスをハイフンに潰した名前でプロジェクトごとに分かれて置かれ、ファイル名も Claude が付ける。取りに行けば読めるが、そこに何かあることを思い出さない限り取りに行かない。
この2つが重なると、書いたものが古くなっても気づかない。実際、あるプロジェクトでは記憶が7月上旬で止まったまま、その後1か月以上も作業を続けていた。リポジトリの外にあるので git status にも差分にも出ず、目に入る機会がない。
行き先が2つに分かれること自体も困る。同じ話が両方に書かれ、片方だけ更新されて食い違う。
まとめると、望みは2つ。AIには読んでほしい。ただし、目に見えるところで、自分の手で管理したい。
行き先を Claude に任せると、この両立が崩れる。何があるかを把握できないだけでなく、ファイルを作るのも名前を付けるのも更新するのも Claude の側になり、自分では手を入れなくなる。任せてよいのは作業であって、置き場所ではない。
8. もっと便利に使う
Section titled “8. もっと便利に使う”ここからは、無くても方式は回る上乗せ。GitHub に上げた人、Codex も併用する人向け。
8-1. GitHub を使うと、何も設定せずにできること
Section titled “8-1. GitHub を使うと、何も設定せずにできること”GitHub に置くと、何も設定しなくてもメモが Wiki のように使える。GitHub Wiki 機能を有効にする必要すらない。
- フォルダを開くと README.md が表示される：GitHub で
notes/を開くと、その中にREADME.mdがあればファイル一覧の下に自動でレンダリングされる。索引を1枚置けば、それがそのままnotes/のトップページになる（→ §6-1） - メモ同士のリンクがそのまま辿れる：
.mdをクリックすればレンダリングされた状態で表示され、[text](other-note.md)の相対リンクもそのままクリックして移動できる（→ MDB 9-2）。ページを行き来しながら読める、というのが Wiki らしさの正体 - 検索が使える：リポジトリページの検索窓から、メモの全文検索ができる。専用ツールの検索機能を覚える必要がない
- 履歴で「いつ考えが変わったか」が追える：コミット履歴を見れば、そのメモがいつどう書き換わったかが差分で分かる。「前はこう考えていたが、ここで方針を変えた」が残る。ノートアプリのメモ機能にはこれがない
8-2. ローカルでMarkdownファイルを読むなら
Section titled “8-2. ローカルでMarkdownファイルを読むなら”レンダリングして読む方法は複数ある（→ MDB 9）。作業中に一番手間が少ないのは、Claudeデスクトップアプリの 縦三点（⋮） メニューから ファイル を開く方法（→ MDB 9-1）。Claude Code で書きながらそのまま確認できる。
8-3. AGENTS.md を symlink にして Codex とも共有する
Section titled “8-3. 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 では注意が要る。symlink を作るのに管理者権限か開発者モードが必要で、Git の設定によっては本物のリンクにならず「CLAUDE.md という文字列が1行入っただけのファイル」になることがある。
Windows の人と共有するリポジトリでは、symlink ではなく import を使う。CLAUDE.md の中に @AGENTS.md と書けば、Claude Code が起動時に AGENTS.md を読み込む。実体は AGENTS.md ひとつのままで、Claude Code だけに読ませたい指示を後ろに足すこともできる。
@AGENTS.md
## Claude Code 向けの追加`src/billing/` を変更するときは plan mode を使う。公式ドキュメントもこの順で案内していて、symlink のほうは「Claude 固有の内容を足す必要がないなら」という位置づけ。Windows では import を使うようにと明記されている（→ CLAUDE.md のドキュメント）。
9. 補足：ほかのやり方との違い
Section titled “9. 補足：ほかのやり方との違い”「Claude のメモリ機能ではだめなのか」「それ Obsidian でやることでは」「Notion に書けばいいのでは」「Google が OKF という仕様を出したはず」「それドキュメント駆動開発では」と思った人向け。5つ並べるが、結論としてはどれとも対立していない。
ツール組み込みのメモリ機能との違い
Section titled “ツール組み込みのメモリ機能との違い”Claude Code にも Codex にも、セッションをまたいで記憶を持つ機能がある。便利だが、in-repo 方式とは向きが逆になる。
| ツール組み込みのメモリ | in-repo | |
|---|---|---|
| 置き場所 | ホームフォルダの下（リポジトリの外） | リポジトリの中 |
| git に乗るか | 乗らない | 乗る |
| 別のマシン | 付いてこない | clone すれば付いてくる |
| 他のエージェント | 読めない | 読める |
置き場所は、Claude Code が ~/.claude/projects/ の下、Codex が ~/.codex/memories/（2026-08 時点）。Claude Code はプロジェクトごとにフォルダを分けていて、その単位は git リポジトリ。同じリポジトリの中なら、どのサブフォルダで起動しても同じ記憶を共有する。フォルダ名はそのリポジトリのパスの / を - に置き換えたものになるので、~/github/bbs-sample で作業していたならこうなる。
~/.claude/projects/-Users-yto-github-bbs-sample/ memory/ MEMORY.md ← 索引。1メモ1行 project_deploy_guide.md ← メモ本体開いてみると、やっていることは in-repo 方式とほとんど同じ。素の Markdown で、1テーマ1ファイルで、索引が1枚ある。違うのは置き場所だけ。
どちらもリポジトリの外なので、プロジェクトを clone しても記憶は付いてこないし、相手のエージェントからは見えない。「clone すれば経緯ごと手に入る」という利点と正面からぶつかる。
ただし「移せない」わけではない。上のとおりただの Markdown なので、notes/ にコピーすれば移せる。保存先そのものを変えることもできる。settings.json に autoMemoryDirectory を書けば置き場所を指定できるので、リポジトリの中に向けてしまえば git に乗る（指定できるのは絶対パスか ~/ で始まるパスだけで、リポジトリからの相対では書けない）。Claude Code しか使わず、マシンが1台なら、置き場所の問題はこれでほぼ解決する。
それでも残る違いがある。ツール組み込みのメモリは、短く保つように作られている。索引にあたる MEMORY.md は先頭200行（または25KB）までしか読み込まれず、超えた分は次に読むときに落ちる。溢れそうになったら、古いエントリをまとめるか捨てるかすることになる。詳しい話は別のファイルに移せるが、索引から消えれば Claude はその存在を知らない。
notes/ は逆で、増える前提・捨てない前提。撤回した方針も消さずに残す（→ §6-2）。記憶と記録の違い、と言ってもいい。ツール組み込みのメモリは Claude が次に動くための記憶で、notes/ は後から読み返すための記録。同じ Markdown を同じ場所に置いても、運用の向きが逆になる。このサイトのリポジトリでいうと notes/ は75本あり、索引の notes/README.md は119行。まだ200行には届かないが、片方に上限は無く、もう片方には有る。
もう1つの違いは、2つのエージェントを同時に使うときに出る。Claude Code と Codex を並行して回すなら、どちらに書いても片方からは見えないので、記憶を同期し続ける仕掛けを自分で用意することになる。in-repo なら置き場所がそもそも1つなので、同期という問題が発生しない。同期の仕組みを考えるより、最初から1か所に置くほうが手軽、というのが選んだ理由。
とはいえツール組み込みのメモリを捨てる必要はなく、住み分けの問題。リポジトリに紐づかない個人の好み（「push は指示があるまで待つ」など）はツール組み込みのメモリに置き、プロジェクトの知識は in-repo に置く。
Obsidian との違い
Section titled “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 として開けばよい。移行のコストはほぼゼロ。今は持たないが、いつでも持てる。
Notion との違い
Section titled “Notion との違い”Notion はここまでの2つと事情が違う。MCP があるので「AIが読めない」が当たらない。
Notion MCP は Notion 公式のリモートサーバーで、OAuth でつなぐと Claude Code や Codex から Notion の中を検索・作成・更新できる。ローカルで動かす版（notion-mcp-server）もあるが、Notion 自身がホスト版を優先していて、そちらのリポジトリには issue と pull request を積極的には見ていないと書かれている。
そのうえで、in-repo と違うところが3つ。
- つなぐ手間がエージェントごとにかかる：MCP の設定と OAuth の認証を、Claude Code でも Codex でもそれぞれやる。in-repo はただのファイルなので設定が要らない
- コードと別の場所にある：エージェントはリポジトリを読みながら、別のサービスへ取りに行くことになる。clone してもメモは付いてこないので、§7 で見た「行き先が分かれる」に近い状態が、リポジトリと Notion の間で起きる
- 履歴の保持がプラン次第：ページ履歴は無料プランで7日、Plus で30日、Business で90日、Enterprise で無制限（2026-08 時点）。git は期限が無く、しかもコードの変更と同じ履歴に乗る
逆に Notion のほうが強いのは、人と共有するとき、スマホから読むとき、データベースやビューで整理したいとき。in-repo にはできないことが並ぶ。
住み分けとしては、人と共有する知識は Notion、コードと一緒に動く経緯は in-repo。なお §7 で挙げた「自分の目に入る」は Notion でも満たされる（むしろ見やすい）。ツール組み込みのメモリ機能と違うのはここで、Notion を使っている人が失うのは可搬性と履歴であって、把握のしやすさではない。
Google OKF との違い
Section titled “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 時点」と冒頭に書いておくと、後から読んだときの扱いが決めやすい。
ドキュメント駆動開発との違い
Section titled “ドキュメント駆動開発との違い”ここまでの4つと違って、これは置き場所ではなく書く順序の話。
ドキュメント駆動開発（README 駆動開発とも呼ぶ）は、実装より先に、使う人向けのドキュメントを書く。提唱した Tom Preston-Werner は「Write your Readme first」、つまりコードもテストも書く前に README を書けと言っている（→ Readme Driven Development）。書いたドキュメントがそのまま仕様になるので、設計の問題を早い段階で見つけられる。
§4 の流れにも同じところがある。1 から 5 で調べて決めてから 6 で作っていて、「さっきのメモに書いた方針どおりに作って」と言えるのは、メモが仕様として働いているから。
違うのは3つ。
| ドキュメント駆動開発 | in-repo | |
|---|---|---|
| 何を書くか | これから作るものの仕様 | 判断の経緯 |
| 古くなったら | 更新する。仕様なので古いと困る | 残す。撤回した判断も消さない |
| 実装しないもの | 書いたものは作る前提 | 調べただけ、見送ったものが残る |
3つ目の差がいちばん大きい。§4 で見送った機能の調査結果は、仕様書には書かない。読む相手も違って、README は利用者に向けたもの、notes/ は作り手と AI に向けたもの。
対立はしないので、両方やってよい。仕様を1枚書いて、その横に経緯を残していけばいい。
10. 付録：ルールノートの中身
Section titled “10. 付録：ルールノートの中身”§2-1 で置くファイルの全文。そのままコピーして使える。長いので細かく読み込まなくてよいが、何をさせるものかは見ておく（→ §2 の囲み）。中身は yto-skills の SKILL.md と同じもので、更新はあちらが正。
冒頭の --- で囲まれた部分は、スキルとして使うときの設定。ルールノートとして置くぶんには使われないが、そのまま残してよい。
---name: in-repo-notesdescription: 調査・検討の経緯や決定を、専用ツールではなく作業中のリポジトリの中に Markdown で残す（in-repo 方式）ときに使う。「記録して」「notes に残して」「メモっといて」「あとで調べたい」「決定として残して」「作業メモの置き場所を作って」などで起動する。置き場所の判断・ファイル名・テンプレート・索引の更新までを担当する。---
# in-repo 方式で作業メモを残す
調査メモや知見を、専用ツールではなく**対象リポジトリの中に素の Markdown で置き、git で版管理し、AIエージェントが直接読み書きする**やり方。ツール組み込みのメモリ機能（リポジトリの外に置かれる記憶）は使わない。clone すれば記憶も付いてきて、どのエージェントからも読めるのが利点。
## 大原則：リポジトリに実在するものに合わせる
作業する前に、そのリポジトリに何があるかを1回だけ確認する。
- `notes/`- `notes/README.md`（索引）- `DECISIONS.md`（決定ログ。リポジトリのルートに置かれることが多い）- `notes/INBOX.md`（思いつきの捕捉）- `CLAUDE.md` / `AGENTS.md` にメモ運用の記述があるか
そのうえで次を守る。
- **無いファイルの話はしない。** 勝手に作らないし、「DECISIONS にも書きますか」と聞かない- **プロジェクトの `CLAUDE.md` に指定があれば常にそちらが優先。** ここに書いた既定より強い- 上のどれも無い場合は「立ち上げ」の節へ
## どこに書くかの判断
分岐は「確定した方針か、それ以外か」の1回だけ。迷ったら `notes/` に書く。
| ユーザーの意図 | 行き先 || --- | --- || 今すぐ知りたいだけ（残さなくてよい） | 会話で答えるだけ。ファイルを作らない || 忘れたくないが、まだ調べない | `notes/INBOX.md` に1行（無ければ会話で確認） || 調べた内容を残したい | `notes/<topic>-<YYYY-MM-DD>.md` を1本 || 方針が確定した | `notes/` に経緯を書き、`DECISIONS.md` に1行（あれば） || 今後ずっと守らせたいルール | `CLAUDE.md` に数行 |
**デフォルトでは記録しない運用のリポジトリもある。** `CLAUDE.md` に「明示の指示があったときだけ記録する」とあればそれに従い、指示が無いときは会話で答えるだけにする。
## ノートの書き方
- 1テーマ1ファイル。`notes/` 直下にフラットに置く（サブディレクトリを作らない）- ファイル名は `<topic>-<YYYY-MM-DD>.md`。topic は内容が見分けられる具体的な語にする- **topic は英数字とハイフンで書く**（本文は日本語でよい）。日本語のファイル名は `git status` でエスケープ表示になり、GitHub の URL もパーセントエンコードされて扱いにくい。ユーザーが日本語のファイル名を指定した場合はそれに従い、既存ノートが日本語で揃っているリポジトリでもそちらに合わせる- 日付はそのメモを書いた時点（通常は今日）- 書く前に、既存のノートに同じテーマが無いか確認する。あれば新規作成せず追記する
テンプレート：
```markdown# タイトル
- **作成日**: YYYY-MM-DD- **目的**: このメモが何のためのものかを1〜2文で- 関連: [他のノート](other-note.md)
## 本文の見出し
（本文）
## 参照
- （出典URL）```
- 冒頭の「目的」は必ず書く。後から読む人が最初の3行で判断できるようにするため- **出典は2か所に置く。** 本文中の、その話が出てくる場所にリンクを直接置き、そのうえで末尾の `## 参照` に一覧としてまとめる（同じ出典は何度引いても1行）- 末尾だけにしない。ノートは書き足され、並び替えられ、一部だけ切り出されるので、離れた場所にある出典リストは本文との対応が黙って壊れる。ファイルの一部だけを読むときにも視界に入らない- 出典が多くて本文が読みにくくなるなら、GitHub の脚注記法 `[^ラベル]` を使ってよい。ラベルは `[^1]` のような番号ではなく `[^passkey-docs]` のような語にする（番号だと並び替えで静かにずれる）- ノート間リンクは標準 Markdown 記法 `[text](file.md)` を使う。`[[wikilink]]` は GitHub で生の文字列として表示されるので使わない- 記憶で断定しない。UI手順・仕様・価格などは一次情報で裏を取り、取れなければ「未確認」と明記する- 太字 `**` を全角の括弧・句読点に隣接させない（GitHub の Markdown で `**` が閉じず生のまま残るため）。✗ `**「型」**を` → ✓ `「**型**」を`
## 索引・決定ログ・Inbox（あるときだけ）
### notes/README.md がある場合
ノートを追加したら、**必ず**索引に1行足す。忘れると索引が実態とズレる。既存の書式（テーブルか箇条書きか、新しいものが上か下か）に合わせる。概要は1〜2文まで。
### DECISIONS.md がある場合
**確定した方針のときだけ**1行追記する。調査・検討段階のものは書かない。
- 書式は既存行に合わせる（日付・決定・根拠・詳細メモへのリンク）- 追記のみ。過去の行を書き換えない- 方針を撤回したときは、古い行を消さずに「〔撤回〕」と印を付け、新しい行を足す- 根拠の詳細は `notes/` のメモに書き、そこへリンクする
### notes/INBOX.md がある場合
`- YYYY-MM-DD 内容` の形式で1行追記するだけ。分類もタグ付けもしない。正式なノートに昇格させたら、Inbox の元の行を消す。
## 二重に書かない
索引も決定ログも、メモ本体と同じ説明を2箇所に書かない。
- `notes/README.md` の概要は1〜2文- `DECISIONS.md` は結論と根拠の要点まで- 詳細・調査の過程・却下した案はメモ本体に書き、索引からはリンクする
索引を肥大させると、分けている意味が消える。
## 立ち上げ（何も無いリポジトリで頼まれたとき）
`notes/` から作る。索引・決定ログ・Inbox は**この時点では作らない**（必要になってから足すもの）。
1. `notes/` を作る2. `CLAUDE.md` に数行だけ追記する
```markdown## 作業メモ
調査・検討の経緯は notes/ に `<topic>-<YYYY-MM-DD>.md` の形式で置く。topic は英数字とハイフン（本文は日本語でよい）。冒頭に作成日と目的、末尾に「## 参照」を書く。判断の背景を知りたいときは notes/ を読むこと。```
3. Codex など他のエージェントとも共有するなら、`AGENTS.md` を `CLAUDE.md` への symlink にする（`ln -s CLAUDE.md AGENTS.md`）。ただし Windows では symlink の作成に管理者権限か開発者モードが要り、Git の設定によっては実体化せずに壊れる。その場合は symlink をやめ、`CLAUDE.md` の中に `@AGENTS.md` と書いて読み込ませる（公式もこちらを案内している）
## 注意
- **リポジトリは Private を前提にする。** メモには公開前のURL・認証の状態・人の名前・ボツにした案などが自然と混ざる。Public リポジトリの `notes/` に書くよう頼まれたら、書く前に「これは誰でも読める状態」と一言指摘する- **秘密は書かない。** APIキー・トークン・パスワードはメモにも書かない- **push は明示の指示があるまで待つ。** コミットまでは自動でよい2026-08-09 (last updated: 2026-09-18) 
タツヲ (yto)