agent-carnet

Agent Carnet

.carnet/<category>/<slug>.md の下に、ディスク上で共有できる Markdown ノートブックを作成する小さな CLI です。ノートのデフォルトの有効期間は 30 日で、読み込むか適用するたびにリセットされます。有用なノートは残り、古くなったノートは自動的に .trash/ に移動します。

クイックリファレンス

# Save (always pass --summary and --agent claude-code)
echo "body content" | agent-carnet save deps/iconv-issue \
  --summary "iconv-esm v0.7 types broken — pin to v0.6" \
  --agent claude-code \
  --tags compat,esm

# Recall
agent-carnet find iconv               # search summaries (does NOT bump lifespan)
agent-carnet list                     # category-grouped overview, sorted by last_used
agent-carnet list --sort use_count    # most-applied notes first
agent-carnet show deps/iconv-issue    # read full content (bumps last_used; weak use signal)

# Mark as actually applied (strong use signal — bumps last_used + use_count)
agent-carnet used deps/iconv-issue

# Maintain
agent-carnet move <from> <to>
agent-carnet rm <path> --yes

サブコマンドのすべてのフラグがわからない場合は、agent-carnet <command> -h を実行してください（例：agent-carnet save -h、agent-carnet used -h）。各サブコマンドは、ファイルシステム操作を実行せずに、必須引数、オプション、使用例に絞ったヘルプを表示します。

保存するタイミング

セッションをまたいで残す価値のある情報を見つけたら、積極的に保存してください。

• 導き出すのに手間がかかった調査結果
• コードベースのわかりにくいパターンや注意点
• 難しい問題の解決策
• アーキテクチャ上の決定とその理由
• 後で再開する可能性がある作業

呼び出すタイミング

関連する作業を始める前や、すでにコンテキストが存在する可能性があるとき：

• agent-carnet find <topic> — 概要をすばやく確認します
• agent-carnet list <category> — フォルダーを確認します
• agent-carnet show <path> — 実際に読み込みます（last_used がリセットされます。内容が重要な場合にのみ使用してください）

used を呼び出すタイミング

carnet が実際に作業に役立った後に、agent-carnet used <path> を呼び出してください。

• 記録された修正を適用し、バグが解決した。
• 仮説を再検証する前に carnet を参照し、無駄な試行を避けられた。
• 新しいコードで独自の名称を考案せず、vocab carnet に記載された標準名を使用した。

used は use_count を増やします。これはセッションをまたいで保持される重要度の指標で、後から読む人が重要なノートを見つけられるようにします（agent-carnet list --sort use_count）。

carnet を読むだけではカウントされません。show はノートの有効期間を維持します（弱いシグナル）。used は、そのノートを保持する価値が実際にあった理由を記録します（強いシグナル）。

厳守事項

• --summary は必須です。要約だけを読んだ次の読者（または次のエージェント）が、続きを読むべきかどうか判断できるよう、明確に書いてください。
• --agent claude-code は必須です。
• find は何も更新しません。show は last_used を更新します。used は last_used を更新し、さらに use_count を増やします。
• updated が記録するのは内容の変更のみです（save、save --update）。last_used とは独立しており、有効期間の基準にはなりません。
• 30 日後の期限切れは自動処理されます。手動でクリーンアップしないでください。keep: true を指定すると、ノートは恒久的に保持されます。
• 自動整理は CLI の呼び出しごとに実行されます。削除された carnet は、完全に削除されるまで 7 日間 .carnet/.trash/ に保存されます。

パスの規則

• <category>/<slug> — ケバブケースを使い、先頭のスラッシュや .. は含めないでください。
• カテゴリーはフォルダーです。必要に応じて自由に新規作成できます。
• サブカテゴリーも使用できます。deps/esm/iconv-issue のようなパスも有効です。

references/ を読むタイミング

日常的なノート管理には、この SKILL.md だけで十分です。references/ ファイルを開くのは、以下の特定のケースに該当する場合に限ってください。これらは常時読み込むコンテキストではないため、必要性が不明な段階で先読みしないでください。

このファイルを読む	タイミング
references/cookbook.md	プロジェクト用語の tags: [vocab] やデバッグでの無駄な試行の tags: [hypothesis] など、タグベースのパターンを使う（または質問される）場合です。このファイルでは、そのパターンの本文や meta: の構成も含め、全体の使い方を説明しています。
references/frontmatter.md	meta: 拡張名前空間の読み書きが必要な場合、通常とは異なる lifespan / keep を設定する場合、または見慣れない frontmatter フィールドが保存時に保持されるかどうかを理解する必要がある場合です。

どちらにも該当しない場合は、references/ を読まないでください。このファイルの基本部分で、日常的な save／find／show／touch／move／rm の操作をすでにカバーしています。