
claude-code-memory
Claude Codeの記憶を外部DBに保存し、セッション間で知識・決定事項・アクティビティを永続化する
- version
- 0.1.0
- GitHub stars
- 5
Install
/plugin install claude-code-memory@calm-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add isizono/cc-memory.
Contents
Discovered from sourceSkills 33
activity-finish
現在のアクティビティを完了にする。完了ではなく、戻ってくる前提で離れる(中断する)ときは末尾の「中断する」節に従う。
手順
-
対象の特定: 「現在のアクティビティ」を以下の優先順位で特定する
- このセッション内でcheck-in・作成したactivityを対象にする
- 候補が複数ある場合は1ターンだけどれを完了にするか確認する
- セッション内に該当がなければ
get_activities(limit=15)で一覧を提示し選んでもらう(limitを省略するとデフォルト5件になり対象が一覧から漏れうるため明示する。タイトルベースで提示し、内部ID・数値は表示しない)
完了ではなく中断・切り替えの意図(「一旦ここまで」「今日はここで止める」など)なら、手順2以降ではなく「中断する」節へ進む
対象がorch(
orchタグが付き、説明の先頭に担い手欄があるもの)なら、この手順の続きに進まずorch skillの「終える」節へ進む。担い手欄が無ければorchではないので、このまま続ける -
終了条件(goal)の確認: 手元に今のgoalブロックが無ければ
get_goal(activity_id=...)で読み直し、labelを見る(get_goalはcheck_inと違いactivityのstatusを変えない読み取り専用なので、statusを書き換えずに確認できる)。以下のgoal_idはget_goal応答のgoal_id_rawを指す -
止めているaskの処理: このactivityを止めている未決着のask(未回答、または回答済みで未triage)を取得する。
get_asks(blocking_activity_id=...)(未回答)とget_asks(blocking_activity_id=..., triage_pending_only=true)(回答済み未triage)で読む。update_activity(status="completed")の応答にpending_asksが付いたときも同じ一覧である(付いていたら、完了後でも次の判断を行う。完了自体は止められない)。0件なら次へ進む。1件以上あれば、askを1件ずつ次のとおり判断する- 続きの残タスクがあるなら、そこへ付け替える(原則): 残タスクがすでに別のactivityとして存在するならそのactivityへ、無ければ activity-start skillで先に起こしてから、
update_activity(activity_id, move_asks_to=<新activityのid>, move_ask_ids=[<askのid>])で付け替える。完了と同じ呼び出しにmove_asks_toを含めてもよい(move_ask_idsを省くと未決着askを全件付け替える) - 実質決着しているなら記録して閉じる: ユーザーが別の場で同じ件に答えた、会話の中で結論が出ている、など答えが既に分かっているaskは、その答えを
add_decisionsで決定事項として記録してから片付ける。未回答ならwithdraw_ask、回答済み未triageならtriage_ask(決定事項にした内容はpromote、そうでなければdismiss) - 残タスクが無く、そのaskがまだ必要なら: それを待つactivityをその場で起こして(activity-start)付け替える
- 不要なら取り下げる: 未回答なら
withdraw_ask、回答済み未triageならtriage_ask(action="dismiss")
付け替え・取り下げをせずに完了させると、askは完了済みのactivityにぶら下がったまま、後から作業を引き継ぐ者に届かない
- 続きの残タスクがあるなら、そこへ付け替える(原則): 残タスクがすでに別のactivityとして存在するならそのactivityへ、無ければ activity-start skillで先に起こしてから、
-
labelに応じて完了させるundefined(goal無し):update_activity(status="completed", closed_by="user", closed_reason=...)。事後にgoalを促すことはしない。ただし、ユーザーがその場で「何をもって終わったか」を条件として言ったときだけ、set_goal(activity_id, goal={"new": {...条件はstate="satisfied"か理由付きwaivedで作成...}})で全条件を終端にして作り、続けてjudge_goalで判定する(update_activityは呼ばない。activityの完了はjudge_goal側で行われる)not_needed(不要印):update_activity(status="completed", closed_by="user", closed_reason=...)。不要印は「この activity には終了条件を置かない」という明示の印なので、事後にgoalを作る例外は適用しないactive(openの条件が残る): 1ターンだけ確認し、ユーザーの選択に応じて次のいずれかにする- 残りの条件を理由付きでwaivedにしてから達成扱いにする:
update_goal(goal_id, changes=[{"op":"set","id":<条件id>,"state":"waived","note":理由}, ...])→judge_goal(goal_id, verdict="achieved", judged_by="human")(waivedにするとsatisfiedが0件になる場合はこの選択肢を示さない。全条件のidが要るときはget_goal(activity_id=...)で確認する) judge_goal(goal_id, verdict="failed", note=理由, judged_by="human")で閉じる- 同じgoalに未完了の兄弟activityが残るなら、このactivityだけ
update_activity(status="completed", closed_by="user")(goalは未判定のまま残る)
- 残りの条件を理由付きでwaivedにしてから達成扱いにする:
judge_ready(判定待ち): 手元のgoalブロック(またはget_goalの応答)のopen_questionsに未決があれば畳むか1ターン聞く。そのうえで条件のうちsatisfiedが1件以上あればjudge_goal(goal_id, verdict="achieved")、0件ならjudge_goal(goal_id, verdict="failed", note=理由)か条件を足す。judged_byは、goalに紐づく未完了activityがこの1件だけなら"human"(/afの起動自体をgoal全体の完了明言とみなす)、他にも未完了activityがあれば"session"closed(判定済み):update_activity(status="completed")だけを呼ぶ。closed_byは渡さない(サーバーがclosed_by="goal_judge"を自動で書く)
-
完了記録の追記:
descriptionの末尾に完了記録を追記する。日付に加えて、会話から自明な範囲で「何がどうなって終わったか」を一行添える(例:\n\n## 完了\nYYYY-MM-DD ○○を実装しPRを作成して完了)。自明でない場合はユーザーへの質問はせず日付のみ記載するupdate_activity(status="completed", ...)で閉じた場合は、そのまま同じ呼び出しにdescriptionを含めてよいjudge_goalで閉じた場合は、閉じた後にstatusを渡さないupdate_activity(activity_id, description=...)で追記する(既にcompletedのactivityへ再度status="completed"を渡しても、サーバー側のガードにより閉じ方の記録は書き換わらない仕様のため、statusは省略すれば足りる)- ログは残さない(軽量にサクッと終わらせる)
-
完了したことをユーザーに一言伝える。goalを判定した場合は判定したこと(達成/未達)も一言添える
- 閉じたアクティビティが
[議論]または[設計]で、次フェーズ([設計]/[作業])が自然に続く内容の場合、「次のactivityを作るか」を一言だけ提案する(勝手に作成はしない) - 承認された場合、
add_activityを直接呼ばず activity-start skillに委譲する(重複チェック・related候補特定・IMPLEMENT_WORKFLOW_GUARD先回りをスキップしないため)
- 閉じたアクティビティが
中断する
進行中のアクティビティを完了にせず、再開しやすい状態にして寝かせる。対象は手順1と同じ方法で特定する(対象が0件ならその旨を伝えて終了する)。
-
再開メモの追記
update_activityのdescription引数は全文置換(既存内容とのマージはない)のため、既存descriptionの全文に中断メモを連結した全文を渡すget_activitiesの一覧プレビューはdescriptionの先頭200文字のみを返す。中断メモを末尾に追記すると一覧上で隠れてしまうため、中断メモは既存内容より前に挿入するget_activitiesで選んだ対象のdescriptionは200字に切り詰められている。そのまま連結のベースにせず、get_by_idsで全文を取得してから連結する- 挿入形式(既存description全文の直前に置く):
## 中断メモ (YYYY-MM-DD) - どこまで: ... - 次にやること: ... - ブロッカー: ...(あれば) --- (既存descriptionの全文) - 内容は会話から自明な範囲で埋める。不明な項目があれば1ターンだけ聞いてよい
- 中断→再開→再中断を繰り返すと中断メモが積み重なり、descriptionが肥大化する(
update_activityはdescription変更のたびにembeddingを再生成する)。過去の中断メモが複数溜まってきたら、直近以外を要約・削減することを検討する
-
ブロッカーが人間の判断の場合の紐づけ
- 手順1で書いたブロッカーが人間の判断待ちなら、
get_goal(activity_id=...)で対象アクティビティの終了条件を確認する(goalが未定義・不要印なら何もしない) - 対応する条件があれば、ask-compose skillでaskを起票し、
update_goal(goal_id, changes=[{"op": "edit", "id": <条件id>, "actor": "human", "bound": {"type": "ask", "id": <ask_id>}}])で束縛する。対応する条件がまだ無ければ{"op": "add", "statement": ..., "actor": "human", "bound": {"type": "ask", "id": <ask_id>}}で新規に足す - openの条件がそのまま再開条件になるため、これ以外に再開条件を別立てで書く必要はない
- 手順1で書いたブロッカーが人間の判断待ちなら、
-
statusの変更
- 近く(同じ日〜数日以内)に再開する見込み:
status="pending"に戻す - 明確な再開時期が読めずしばらく寝かせる:
status="snoozed"にする。snoozedは既定3日(環境変数で変更可)経過後、次にget_activitiesが呼ばれたタイミングでpendingへ復活する(バックグラウンドタイマーではなく呼び出し時にまとめて反映されるため、get_activitiesが呼ばれるまでは3日経過後もsnoozedのままになりうる) - 期限を決めず長期棚上げする:
status="shelved"にする。shelvedは自動復活せず、明示的にstatusを変更するまでactive一覧に出てこない - 判断に迷う場合はユーザーに選んでもらう
- 手順1の
description更新とこのstatus変更は、update_activityの同一呼び出しにまとめて渡す(snoozed状態のアクティビティはstatusを指定せず他フィールドのみ更新すると自動的にpendingへ復活するため、呼び出しを分けると意図しないstatus遷移が起きうる)
- 近く(同じ日〜数日以内)に再開する見込み:
-
中断したことと、再開は
check-inから行える旨を一言伝える
中断ではgoalに触れない(手順2のask束縛を除く)。ログも残さない。
注意
/afが呼ばれたこと自体が「終わった」の根拠。goal無し・不要印のactivityでは、エージェント側で「本当に終わった?」等の判定ロジックは入れない- goal付きのactivityでも完了は拒否されない。判定を挟むのは上記の分岐に従うときだけで、goalが未判定のまま
update_activity(completed)を呼んでも通る(応答に付くgoal_hintは知らせであり、拒否ではない) - sync-memory的な記録の棚卸しはしない。あくまで軽量な完了操作
- 完了と中断の境界: 作業が終わったなら完了、戻ってくる前提で離れるなら中断。セッション全体の一括記録の意図(sync-memory)では発動しない
activity-start
新しいアクティビティを作成してcheck-inする。
orchアクティビティ自体の起票と、orchの子の起票は、本スキルではなくorch skillの手順に従う。
手順
-
ユーザーの入力と会話の文脈から、以下3つを判定する:
- タイトル(何をやるか)
- intent(議論/実装/調査/デバッグ/設計/...)
- domain(どのプロジェクト)
-
3つのうち推定できないものがあれば、1ターンだけ聞いてよい。それ以上は聞かない
-
重複チェック:
add_activityを呼ぶ前に、タイトルのキーワードでsearchを実行し、同じ目的のactivity・topicが既にないか確認する(entity_typeは指定せず横断検索し、結果のtypeがactivity/topicの項目を見る)。過去セッションや並行セッションが同じテーマを扱っている可能性があるため、再発明・二重管理を防ぐための必須ステップ- 同じ目的のactivityが見つかった場合は新規作成を提案せず、そのactivityへのcheck-in(再開) を提案する
- 承認された場合、
check_inツールを直接呼ばず check-in skillに委譲する(anchor.pinned/env.hintsフィールドの扱いや出力フォーマットをスキップしないため) - 見つからなかった場合、またはユーザーが新規作成を選んだ場合のみ次のステップに進む
-
related候補の特定: 手順3の検索結果を流用し、関連するtopic/activity/decisionを能動的に洗い出す。会話の文脈から得られる関連先も合わせて候補にする
-
intent:implementガードの先回り: intentが
implementと判定された場合、add_activityはrelatedにtype: "decision"のエントリを最低1件含めないとIMPLEMENT_WORKFLOW_GUARDエラーで弾かれる(add_activityツールdocstring参照)- 手順3〜4で見つかった関連decisionのうち、合意済みのものをrelateする
- 合意済みdecisionが見つからない場合は、「いきなり実装に入る理由」をユーザーに確認し、その回答を
add_decisionsでdecisionとして記録してから、そのdecisionをrelateする
-
作成内容をユーザーに提示して確認を取る
- タイトル、intent、domain、tagsの案を見せる
- 明らかに迷いようがない場合のみ確認をスキップしてよい(例:
/as READMEのインストール手順を更新で対象リポジトリが明確な場合)
-
add_activityでアクティビティを作成する(check_in=True)title: intentに応じたプレフィックスを付ける([議論],[作業],[調査],[設計]等)tags:domain:タグ(必須)+intent:タグ(必須)+ 内容を表す素タグdescription: ユーザーの入力から得られた情報をできるだけ記載。構造の例: 背景(なぜやるか)/ スコープ(何をやるか)/ やらないこと(対象外)。別セッションが引き継げる粒度で詳しく書くrelated: 手順4・5で特定した関連エンティティを紐づける
-
終了条件の3択(手順7で作成した
activity_idに対して行う)orchのアクティビティはorch skillの「なる」節で起票し、goalまでそこで作るので、この3択の対象外。activity-startで作るアクティビティには
orchタグを付けない(orchはorchの目印専用のタグ。話題としてのorchにはorchestration、別の意味ならその意味が分かる別の語を使う)。既存の未判定goalに続く作業の場合は、3択に入る前にここで紐づけて次のステップへ進む。手順3〜4で特定した関連activityのうち続きとなるものについて
get_goal(activity_id=<関連activityのid>)を呼び、返ってきたlabelがclosedでないこと(未判定であること)を確認したうえでgoal_id_rawを控える。控えた値を使ってset_goal(activity_id=<手順7で作成したactivity_id>, goal={"goal_id": <goal_id_raw>})で紐づける。- 会話でユーザーが真偽の付く終了条件を言っている、または言われていなくても会話の意図から推せる →
set_goal(activity_id, {"new": {"handle": ..., "statement": ..., "conditions": [...]}})でそのまま書く。ユーザーの追認は待たず、書いたことの報告もしない。条件には、Claudeが自力で到達できるもの(actor: "claude")を最低1本含める。到達の判定を人間に委ねる条件(actor: "human")も、担い手がhumanになることを理由に確認を挟まず同様に書く - 終わり方の候補が複数あって1つに絞れない、またはこの活動には終わりがあるはずだが何なのか推せない → チャットでユーザーに聞き、定まれば同様に
set_goalで書く。聞いても定まらなければ何も書かない - 常駐運用・同じセッションで閉じる小作業など、終わりの無い活動 →
set_goal(activity_id, {"waiver": "<理由>"}) - 雛形で埋めない。上のどれにも当たらない(まだ終わり方を考える判断材料が無いなど)場合は何も書かない。未定義のまま進めるのは正当な状態である
- 会話でユーザーが真偽の付く終了条件を言っている、または言われていなくても会話の意図から推せる →
-
check-in結果をユーザーに伝える
intent判定ガイドライン
ユーザーの意図からintentを判定する。discussをデフォルトにしない。語句の一致ではなく、ユーザーが何をしたいかの意図で判断する。
| intent | ユーザーの意図 | 例 |
|---|---|---|
investigate | 情報を集めたい・理解したい | /as 検索精度の現状を調べる → 即作成 |
debug | 問題の原因を突き止めたい | /as searchが空配列を返すバグ → 即作成 |
implement | 具体的に作る・変える | /as searchにrecency boost追加 → 即作成 |
design | How/Interface/Edge casesを決めたい | /as 取り消しプロトコルのDB設計 → 即作成 |
discuss | 方針・要件の曖昧さを解消したい | /as LLMの評価方法を考えたい → 確認して作成 |
document | ドキュメントを書く・更新する | /as README更新 → 即作成 |
review | コードの差分を確認する | /as PR#300レビュー → 即作成 |
intentに幅がある場合や不明瞭な場合は、ステップ2・6で確認する。
ask-answer
open askを一覧し、1件ずつ人間に提示して回答を得たらanswer_askで記録する最小skill。トリアージ判定・同型判定・監視ループは持たず、「聞く→答える→記録する」の直線フローだけを担当する。
「askに答える」「open ask消化して」「溜まってるask片付けたい」「判断待ちに回答する」などの依頼で使う。
手順
get_asks()を1回だけ呼ぶ(statusの既定値は"open"なので省略してよい)。ユーザーが明示的にkind/tags等を指定しない限り、追加のフィルタ引数は渡さない。limitはデフォルト(20件)のままでよく、ページネーションのために追加呼び出しを重ねる必要はない。total_countが0件なら「open askはありません」と提示し、answer_askを呼ばずにここで終了する。- 返り値の
asks件数がtotal_countより少ない場合は「上位N件のみ表示(全M件)」と明記してから、1件ずつ順に人間へ提示する。提示はquestion(概要)を中心に、必要ならcontextも見せる。内部ID(id_raw)は表示せず、タイトル・要約ベースで「これは何のaskか」が伝わる形にする。 - 人間から回答が得られたら、その発言をそのまま、または意図を汲んだ文面で
answer_ask(ask_id=<該当askのid_raw>, answer_body=<回答本文>)を呼ぶ。回答本文は人間の判断そのものであり、AIが代わりに考えて埋めない。A/はいのような一言回答も、そのままanswer_bodyに渡してよい(ask-composeのテンプレートが一言回答を許容しているため)。 answer_askが成功し、返り値のnext_stepにトリアージへの誘導が含まれていても、それはこのskillでは実行しない(次のaskへ進む)。対象がすでにanswered/promoted/dismissed等でanswer_askがエラーを返した場合は、エラーをそのまま提示して次のaskへ進む。- 残りのaskについて3〜5を繰り返し、最後まで進んだら完了を短く報告する。
注意
- 回答本文(
answer_body)は人間の発言・意図をそのまま反映したものであり、AIが自分の判断で作文して埋めてはならない - 1つのaskに対して
answer_askが成功するのは1回だけ。既にanswered/promoted/dismissed等になったaskへの再回答は拒否される triage_ask(promote/dismiss)・withdraw_askはこのskillの手順に含めない。答えた後の裁定(一般化ルールとして発効させるか、見送るか)は別経路(次回のcheck-in・get_asks(triage_pending_only=true)を使った非メタask自走裁定等)に委ねる。理由: このskillのスコープは「順に答えるだけ」であり、答えたその場でのtriageまでは含まない設計判断のためanswer_askだけではaskは「回答済み・未triage」として残り、止めているactivityのcheck_inにも回答済み未triageとして出続ける(待ちから外れるのはtriage_askのpromote/dismiss、またはwithdraw_ask)。このskillで回答した後もその状態のままであることを、完了報告時に人間へ伝える- 提示は常にタイトル・question・context等の内容ベースで行い、内部ID(
id_raw)をユーザーに見せない kind="meta"のaskも通常のaskと同じ手順(一覧→提示→answer_ask)で処理できる(answer_askのシグネチャはkindに依存しない)。メタask固有の配置作業(rule-placementskillへの誘導)はこのskillの手順に含めない
関連skillとの境界
ask-compose:add_askを呼ぶ前にquestion/contextを構成する。ask-answerは既に起票済みのaskに答える側であり、起票前の作業は担当しないask-distill:add_ask呼び出し後、similar_asksから同型askの反復に気づいたときにメタaskを起票する。ask-answerは回答フローに専念し、同型判定・メタask起票は行わないask-watch: open askの滞留をMonitorでイベント駆動監視し続けるスキル。ask-answerは1回限りの一覧+回答フローであり、継続監視は行わない
ask-compose
add_askのquestion/context欄を、questionの概要/選択肢/おすすめ、contextの対象activity/背景という構成テンプレートに沿って組み立てる。question/contextの記入品質をここに集約しているため、add_askを呼ぶ前に本スキルの手順を必ず通す。
発動契機
以下のいずれかに該当する場合に発動する。
- AI自発判断: 離席中・セッション跨ぎでしか答えられない判断が発生し、
add_askを呼ぼうとしている場面 - ユーザー明示指示: 「これ聞いといて」「これaskして」「判断委譲しといて」「離席するから後で確認して」「非同期で聞いておいて」「これは私が戻ってから判断する」など、ユーザーが明示的に非同期の判断委譲を指示した場面
いずれの場合も、add_askを呼ぶ前に必ず本スキルの手順(テンプレートに沿った構成)を通す。
対象
add_askのquestion/context欄の構成
add_ask呼び出し後、レスポンスのsimilar_asksから同型askの反復に気づいたときのメタask起票はask-distill skillが担当する。本スキルはメタask化の判定を行わない。
kind="meta"のメタask自体の起票は本スキルを経由しない。ask-distill・ask-watchが各々の組み立て方(question/context/blocksの構成)に従って直接add_askを呼ぶ。
なぜこの構成にするか
askはダッシュボード等、Markdown装飾が効かない環境で読まれることがある。装飾に頼らず「今どの節を読んでいるか」が見出し文字列だけで伝わるよう、節を固定順の構成に分けている。
LINE(askくん)等の通知経路はquestionしか表示せず、contextは別途開かないと読めない。そのため、その場で答えを決めるのに必要な情報(概要・選択肢・おすすめ)はquestionに集約し、前提知識や経緯などcontextを開かなくても答えに支障が出ない情報だけをcontextの背景に置く。対象activityは、contextのどの節よりも前に置く。読み手がまず「これは何の作業の話か」を把握してから背景を読めるようにするためである。
テンプレート
questionには「## 概要」「## 選択肢」「## おすすめ」を、contextには先頭の対象activity行と「## 背景」を記入する分担を基本とする(questionは500字以内の制約があるため、選択肢とおすすめも含めて簡潔に書き切る。詳しい経緯や比較はcontextの背景に逃がす)。
## 概要
- 問題:(何が起きていて、なぜ今判断が要るのかを1-2文で)
- 決めてほしいこと:(Yes/No、またはA/B/Cのどれかを選ぶ、という形に落とし込む)
## 選択肢
- A: 〜 — 良い点:… / 悪い点:…
- B: 〜 — 良い点:… / 悪い点:…
## おすすめ
- 推奨:A(理由:…)
---
一言で答える場合は `A`/`B`/`はい`/`いいえ` だけでもOK
対象activity: 「(このaskが答え待ちで止めているactivityのタイトル。blocksに渡す各activity IDに対応する、人間可読なタイトル文字列。IDそのものは書かない)」
## 背景
- 今のタスク:(このセッションが何に取り組んでいるか。前提知識ゼロで読める粒度で)
- 経緯:(何をしていてこの分岐に当たったか)
- 影響範囲:(この判断がどこまで効くか。可逆/不可逆をここに含める)
- 放置するとどうなるか:(今のままだと何が止まり続けるか)
questionを500字に収める書き方
question本文は概要・選択肢・おすすめの3節を合わせて500字以内に収める必要がある。目安と、超えたときの削り方は次のとおり。
- 概要: 問題1文+決めてほしいこと1文で150字程度に収める
- 選択肢: 2〜3案。1案につき「ラベル — 良い点:◯◯ / 悪い点:◯◯」の1行(60字程度)に圧縮する。良い点・悪い点はそれぞれ10〜15字程度の一言に削る
- おすすめ: 推奨ラベルと理由を1行(50字程度)にまとめる
- 上記の目安どおりなら3択でも400字前後に収まる。それでも超える場合は、①選択肢を2件に絞る、②良い点・悪い点のうち判断に効く方だけ残す、③決めてほしいことの文言をさらに削る、の順で切り詰める。削った詳しい比較や経緯はcontextの背景に書けば情報は失われない
各項目の記入ガイド
概要(questionに記入)
- 問題: 前提を知らない人がこの1-2文だけで「何が起きているか」を理解できるように書く。技術的詳細は背景に譲り、ここでは状況の要約に徹する
- 決めてほしいこと: 自由記述の問いにしない。人間が数秒で答えられる形(Yes/No、A/B/Cのどれか)に必ず落とし込む。「どう思いますか」のような開いた問いは書かない
対象activity(contextの先頭、## 背景より前)
add_askのblocks引数に渡す各activity IDについて、そのタイトル(人間可読な文字列)を対象activity: 「タイトル」の形式でcontextの一番先頭に書く。IDそのものを書いてはいけない(calm内部識別子は読み手に解決できないため)- タイトルは基本、そのセッションが既に
check_inやget_activitiesで取得済みの値をそのまま使う。手元に無い場合のみ、あらためてget_activitiesで解決してから記入する blocksが複数件のときは対象activity: 「タイトルA」、「タイトルB」のようにカギ括弧を読点で区切って1行に収める。件数が多く1行が読みにくくなる場合(目安3件超)は、1行1タイトルの箇条書きに切り替えてよい
背景
- 今のタスク: 読み手がこのセッションの文脈を一切知らない前提で、何に取り組んでいるかを書く
- 経緯: なぜこの分岐に当たったのか、直前の作業の流れを書く
- 影響範囲: この判断が及ぶ範囲を書く。特に「後から取り消せるか(可逆)」「一度実行すると戻せないか(不可逆)」を明示する。不可逆な判断ほど詳しい背景が必要になる
- 放置するとどうなるか: 判断を待たずに放置した場合に何が止まるか、どんな実害が生じるかを書く。緊急度の判断材料になる
選択肢(questionに記入)
- 最低2案は出す。「やる/やらない」のような単純な二択でも、それぞれの良い点・悪い点は省略しない
- questionの500字予算があるため、各案は「ラベル — 良い点:… / 悪い点:…」の1行に圧縮する。詳しい比較が要るならcontextの背景に書く(書き方の目安は前節「questionを500字に収める書き方」参照)
- 選択肢がある場合のみ、各選択肢のラベル(
- A: 〜 — 良い点:…の〜部分。良い点/悪い点の説明文は含めない)をadd_askのchoices引数(list[str])にも渡すことを推奨する。Yes/Noのみで案として列挙するものがないaskではchoicesを渡さなくてよい(省略時はnull扱い)。ダッシュボード等でのボタン表示に使われるため、Markdown本文のラベルと重複してよい choicesには最大3件・1件100字以内という制約がある。Markdown側の選択肢が4件以上ある場合は、「## おすすめ」に近い優先度上位3件のみをchoicesに渡す(残りはquestionの「## 選択肢」節にのみ残す)。ラベルが100字を超える場合は、100字以内に要約してから渡す(詳しい説明はquestionの「## 選択肢」節に残せばよく、choices側で削っても情報は失われない)
おすすめ(questionに記入)
- 必ず1案を推奨する。「どちらでもいい」は書かない(推奨が無いと判断委譲の意味が薄れる)
- 理由は一言で、良い点・悪い点のどちらを重視したかが伝わる書き方にする。「Aがいいと思う」だけで終わらせない。詳しい論拠が要るならcontextの背景に書く
記入例
question:
## 概要
- 問題:夜間バッチでの外部API同期中にレート制限(429)を受けた。リトライ待機時間はAPI側の応答で60分と判明している。
- 決めてほしいこと:60分待ってリトライを続行する(A)か、今回は中断し翌日の定期実行に任せる(B)かを選んでほしい。
## 選択肢
- A: 60分待ってリトライを続行する — 良い点:今日中に完走 / 悪い点:1時間他処理をブロック
- B: 中断し翌日の定期実行に任せる — 良い点:即座にリソース解放 / 悪い点:同期が1日遅れる
## おすすめ
- 推奨:B(理由:アカウント一時停止のリスク回避を最優先。1日の遅延は許容範囲)
---
一言で答える場合は `A`/`B` だけでもOK
context:
対象activity: 「夜間バッチでの外部API同期処理」
## 背景
- 今のタスク:夜間バッチで外部APIから1000件のデータを同期する処理を実行中。
- 経緯:600件処理した時点でレート制限に達した。APIの利用規約上、制限中に再度リクエストを送るとアカウントが一時停止されるリスクがある。
- 影響範囲:可逆。今回のバッチを中断しても、翌日の定期実行で自動的に残り400件を含めて再同期される設計になっている。
- 放置するとどうなるか:判断を待たずに放置すると、バッチプロセスがタイムアウトするまで無応答のまま残り続ける。
goalの条件をこのaskに束縛する
このaskが、goalの条件(担い手human)の待ちを形にするために起票するものなら、次も行う。
blocksには、その条件を持つactivityに加え、同じgoalに紐づく兄弟activityのうち、そのactivityへのcheck_inでも回答待ち・振り分け待ちを出したいものを含めるadd_askの呼び出し後、update_goalで対象の条件を{"op": "edit", "id": <条件id>, "actor": "human", "bound": {"type": "ask", "id": <このaskのid>}}に束縛する
ask を起票するのは、その場で聞けずユーザーが離席中・セッションをまたぐときに限る(発動契機のとおり)。その場で聞けるなら ask を起票せず、聞いて decision-record で決定として記録する。
add_ask呼び出し後: 回答の受け取り方
Claude Codeでは、add_askを呼んだ直後からCALMのhookが裏で回答を待つ。回答(またはpromote/dismiss)されると、hookがこのセッションを起こし、askの番号と状態だけを知らせる。Monitorを張る必要はない。
起こされたら次の順で進める。
get_asks(ids=[<番号>], status=null)で回答を読む(statusを省略すると既定の"open"で絞り込まれ、回答済みのaskが返らない)- 回答に沿って作業を続ける
- statusが
answeredなら、読んだら早めにtriage_askで処理済みにする(決定として残す内容ならpromote、そうでなければdismiss)。回答済み・未トリアージのまま残すと、check_inでの再配達や外部の作業再開の仕組みが同じaskで二重に動くことがある
その場で待つ必要が無いask(後で気づけば十分な優先度のもの)はnotify=Falseで積む。hookは待たず、起こしもしない。積んだ後で待つのをやめたい場合はunsubscribe_askを呼ぶ(待機中のhookも止まる。ただし複数セッションから積まれた同じ問いのaskには使えない)。
積んだaskが、その後の会話の途中で実質決着していると気づいたとき(ユーザーが別の場で同じ件に答えた、議論の中で結論が出た、など)は、その時点で答えを add_decisions で決定事項に記録してから取り下げる(未回答なら withdraw_ask、回答済み未triageなら triage_ask)。askを開いたまま残すと、完了したactivityにぶら下がって誰にも届かない待ちになる。
hookが待つのは最長で約24時間。それを過ぎた場合や、hookの無いハーネス(Codex等)では、SessionStart/UserPromptSubmit hookがこのセッションの登録したaskの解決状況を毎ターン確認して知らせる。
ask-distillとの境界
ask-compose(本スキル):add_askを呼ぶ前に、question/contextの構成を担当するask-distill:add_askを呼んだ後、レスポンスのsimilar_asksを見て同型askの反復に気づいたときのメタask起票を担当する
両者は時系列で別の場面に発動する別スキルであり、混同しない。
ask-distill
add_askが返すsimilar_asks(近傍askの裁定内容=answer_body込み)を読み、同型の問いが繰り返され裁定が一貫していると判断した場合に、判例(answer_bodyの集積)をまとめてメタask(kind="meta")を起票する。メタaskは「この型の問いは今後、判例に従って自己裁定してよいか」を人間に問う一段上の問いであり、一般化ルールの発効そのものではない(発効は人間のメタask裁定を待つ)。
発動契機
add_askのレスポンスを受け取った直後、similar_asksに含まれる過去askのanswer_bodyを見て、以下の両方に該当すると判断したとき:
- 同型の問い(表現は異なっても実質同じ判断軸)が2件以上(
similar_asks内、または過去のget_asks結果と合わせて)繰り返されている - それらの裁定(
answer_body)が一貫している(毎回同じ方針で答えられている)
裁定が割れている・件数が少ない(同型が初出)・similar_asksが空、のいずれかに該当する場合は発動しない。
add_askのdocstringからも本スキルが案内される。
手順
- トリガーaskのblocksを確認する: 今まさに起票したask(直前の
add_ask呼び出しの返り値のid)について、そのadd_ask呼び出しに渡したblocks引数の値をそのまま使う(改めてget_asks等で取り直さない)。 - 判例を集約する:
similar_asksから、同一裁定(answer_body)が繰り返されている件数と内容をまとめる(何件、どんな裁定だったか)。 - メタaskを起票する: 以下の形で
add_askを呼ぶ。question:"この型の問いは今後、判例(N件: 裁定内容の要約)に従って自己裁定してよいか?"context: 集約した判例の詳細(各askの問いと裁定の対応がわかる形で)blocks: 手順1で確認したトリガーaskのblocksをそのまま引き継ぐ(新設のactivityは作らない)kind:"meta"(必須)tags: トリガーaskと同じdomain:タグ +"meta-ask"
- トリガーになった元のaskはopenのまま残す: withdrawしない。「今回この場で自己裁定できるか」はルール3の別判断であり、このskillのスコープ外。
注意
- 手順3のメタask起票は
ask-composeskillを経由しない。本スキル自身がメタask専用の組み立て方(question/context/blocksの構成)を持つため。 - メタaskの裁定(人間の回答)が「自己裁定してよい」であっても、一般化ルールが自動発効するわけではない。発効は人間のメタask裁定でのみ行われ、機械もLLMも勝手に発効しない(
RULESの「## Asks(判断委譲)」節参照)。 - メタask自体も答え待ちの間、渡した
blocksのactivityを止める。トリガーaskと同じblocksを渡すため、二重に答え待ちが積まれる形になるが、これは意図的(両方とも同じactivityの進行を実際に止めている判断待ちのため)。
ask-watch
calmのask store(add_ask/get_asks/answer_ask/triage_ask/withdraw_askが読み書きする、人間の判断待ちaskのインボックス)をMonitorツールでイベント駆動監視するスキル。asksテーブルのstatus='open'件数・last_seen_at・id集合をポーリングし、前回値から変化を検知するたびに全open askを読み直す。表面的な主題は違っても判断構造(問いの型)が同一の同型群がないかをLLM自身が判定し、見つけたら、既に同じ型のメタaskが起票済みでない限り、「この型は今後、人間に聞かずに一般化ルールとして自己裁定してよいか」を問うメタask(kind="meta")を起票する。
背景
ask storeには「同じ判断構造の問いが繰り返されたら、機械が閾値で自動検知するのではなくLLM自身が気づいてメタaskを起票し、その型を今後は自己裁定してよいか人間に問う」という二段構えの設計が既にある。だが実際には、同型askが8件溜まったまま3週間気づかれない事象が起きた。原因は「LLMが気づく機会」が新規ask投稿時の類似ask提示にしか無く、既存の滞留askをLLMが定期的に読み返す機会が無かったこと。ask-watchはこの「読み返しの機会」を、Monitorツールによるイベント駆動監視という形で補う。
pr-watchとの構造的な違い
- トリガー方式: pr-watchは10分毎の固定間隔cronループで動くが、ask-watchはMonitorツールでasksテーブルを10秒間隔でポーリングし、
status='open'の件数・最終last_seen_at・id集合のいずれかが前回値から変化したときだけイベントを発火する。変化がなければ何も起きない - 差分検知ではなく毎回全件精読: イベント自体は差分(変化の有無)で検知するが、変化を検知した後にStep 3で読む範囲は差分ではなく全open askである。これは今回の実害(新規に増えない古い滞留askの見逃し)を防ぐための設計であり、
processed_ask_idsのような既読管理は持たない - 同型判定は機械的閾値ではなくLLMの目視判断: pr-watchの「bot指摘」は機械的に判定できるトリガーだが、ask-watchの「同型群かどうか」はembeddingの類似検索では拾えない(主題の近さは拾えても判断構造の近さは拾えないため)。閾値・キーワード一致等の自動検知ロジックは実装しない。各open askの本文をLLMが読み、判断構造が同一かどうかを都度判断する
- SAを起動しない: pr-watchはbot指摘対応という実装作業(コミットを積む)をSAに委任するが、ask-watchは「読む→判断する→MCPツールを呼ぶ」だけで完結する軽量作業であり、実装コミットのような重い処理が発生しない。イベントを検知したセッション自身が判断から起票までを完結させる。SA spawnは行わない
トリガー条件
以下の状況で使用する:
- ユーザーが「ask storeを監視して」「asksを見張って」「open askの滞留をチェックして」と依頼
/ask-watchの明示呼び出し- 「同型のaskが溜まってないか定期的に見ておいて」のような継続的処理依頼
以下では使用しない:
- 1回限りのask確認(
get_asksを直接呼ぶだけで済む、またはユーザーが今すぐ内容を見たいだけ) - calm自体の使い方説明(
calm:manskillの担当) - 特定1件のaskへの回答(
ask-answerskillの担当)・トリアージ作業(triage_askを直接呼べば済む)
ワークフロー
Step 1: state fileの確認・初期化
- 既存
~/.cc-memory/ask-watch-state.jsonがあれば読み込み、続きとして扱う - 無ければ新規作成する(フォーマットは下記)。state fileは差分検知には使わない(差分検知の主体はStep 2のポーリングスクリプト内の変数
prev)。ここでの役割は起票したメタaskの履歴等、人間が読むための参考ログに限定される
{
"started_at": "2026-08-16T09:00:00Z",
"poll_interval_sec": 10,
"trigger_count": 0,
"filed_meta_asks": [
{"ask_id": 123, "type_summary": "ow解体で前提消滅したactivityの処遇", "filed_at": "2026-08-16T09:00:00Z"}
],
"_notes": "free-text notes for human"
}
filed_meta_asksはローカルの参考ログであり、重複起票防止の判定はこのファイルではなくStep 3の4番目の項目(DB照会)を正とする。state fileとDBがズレても実害が出ない設計にするため
Step 2: ポーリングの起動(Monitor)
Monitorツールを以下のパラメータで呼ぶ:
description: 監視対象がわかる説明(例:"ask store open askの変化監視")timeout_ms:1800000(Monitorの上限値。これより大きい値を渡しても30分に切り詰められるため、常に上限を明示する)command:uv run --no-sync --directory "${CLAUDE_PLUGIN_ROOT}" python "${CLAUDE_SKILL_DIR}/scripts/poll.py"(30分ごとに張り直すたびの暗黙の依存同期を避ける。プラグインキャッシュ経由であれば起動時のhookが先に同期済みのため、venvが未同期になることはない)
Monitorはtimeout_msの上限である30分で必ず失効し、そのタイミングで失効通知が届く。監視を続ける場合はこのStep 2をそのまま繰り返してMonitorを張り直す(re-arm)。失効通知は「open askに変化があった」ことを意味しないため、Step 3の処理には進まず張り直すだけでよい。
scripts/poll.pyはopen askの「件数・最新last_seen_at・id集合」のいずれかが変化した瞬間だけ1行出力する。GROUP_CONCAT(id)まで比較に含めているのは、件数が同じでもid構成が入れ替わる変化(1件closeして1件openになった等)を取りこぼさないため。出力される値はあくまでトリガーの参考情報であり、実際に読むべきask本文はStep 3でget_asksから取得する(DBを直接sqliteで読むのはポーリングの軽量化のためで、questionやcontextの中身までDB越しに読み取ることはしない)。
Step 3: 変化検知時の処理手順
Monitorの通知には2種類ある。ask store changed: ...という1行を伴う変化検知の通知を受け取ったときは、以下を実行する。cronループと異なり同一セッション内のイベントとして届くため、prompt文字列を読み直す必要はなく、以下の手順をそのまま適用する。Monitorが30分で自動失効したときの失効通知は変化検知ではないため、以下の手順には進まず、Step 2の要領でMonitorを張り直すだけでよい。
- state file読み込み: 無ければStep 1へ戻る
- 全open ask取得:
get_asks(status="open", include_stats=true, limit=100)。total_countがlimitを超える場合はoffsetを進めて全件回収する - 同型群の判定: 取得した全askの
question・context・tagsを読み、「主題は違うが判断構造(問いの型)が同一」の集まりがないかLLM自身が判断する。目安として同型2件以上が集まっている状態を対象にするが、これは判断のガイドラインであり、機構が自動的に判定する固定閾値ではない。対象はopen ask同士の同型なので、裁定が既に一貫しているかどうかは問わない(まだ誰も回答していないケースが主) - 重複起票防止の確認: 同型群を見つけたら
get_asks(kind="meta", status=None, limit=100)で既存の全メタask(open/answered/promoted/dismissed問わず)を確認する- 既にopenなメタaskがあれば起票しない。短報に「既知の型、裁定待ち」として記載
- 既にpromoted済み(発効済み=自己裁定してよいと人間が既に判断した型)であれば起票しない。ただし該当の同型askがまだopenで残っていること自体は「本来もう自己裁定できたはずの型が取りこぼされている」観察なので短報に記載する(ask-watch自身がwithdrawや自己裁定を代行することはしない、スコープ外)
- 既にdismissed済みであれば起票しない。短報に記載
- 該当なしの場合のみ次の項目へ進む
- メタaskの起票: 重複がなければ
add_askを呼ぶ(詳細な組み立て方はStep 4参照) - state file更新:
trigger_countを+1、起票した場合はfiled_meta_asksに追記 - ユーザーへ短報: 検知した同型群の有無・起票したメタaskの有無(既知判定になったケースも含めて簡潔に)
Step 4: メタaskの組み立て方
add_ask呼び出しの各引数の組み立て方:
- question: 型の判断構造を具体的に書く。「主題」ではなく「問いの構造」を書くこと。例:「前提が消滅したactivityをclose/再定義/継続のどれにするかという判断は、今後は◯◯の基準で人間に聞かずに自己裁定してよいか」
- context: 同型群に含まれる各open askの
id・question・出現状況(occurrence_countがあれば)を列挙し、なぜ同型と判断したかの根拠を書く。既に答え済み(answered/promoted)の近い型が過去にあれば、その裁定内容も参考情報として添える - blocks: 同型群の各askが持つ
blocks(activity id)の和集合。1件のaskから起票する場合はそのaskのblocksをそのまま使う(既存のask-distill skillと同じ扱い)。複数askにまたがる場合は全askのblocksを合わせる - tags: 同型群の各askが持つ
domain:タグを全て含める(主題が異なればdomain:タグも複数になりうる、複数個の付与自体は問題ない)。加えて"meta-ask"を素タグとして必ず付与する
Step 5: 監視停止
ユーザーから「監視止めて」「もういい」「ask-watch停止」等の依頼があればTaskStopを実行し、Monitorタスクを停止する。Monitorはどのみち30分で自動失効するため、停止依頼が来る前に失効している場合は張り直さずそのまま終了してよい。session終了でも監視は終了する。
出力フォーマット
各検知後の短報フォーマット:
**ask-watch報**: <同型群N件検知/検知なし>、<メタaskM件起票/起票なし>
- (件があれば箇条書きで詳細: 型の要約、対象askのid、既知/新規の別)
何もなければ1行(同型群なし、起票なし。)で十分。
注意事項
- Step 4のメタask起票は
ask-composeskillを経由しない: 本スキル自身がメタask専用の組み立て方(Step 4参照)を持つため - Monitorでイベント駆動監視する: 固定間隔で毎回ターンが起動するcron方式ではなく、Monitorツールでバックグラウンドのシェルスクリプトを走らせ、asksテーブルに変化があったときだけ通知として受け取る。変化がなければターンは発生しない
- 全件精読の理由: 差分検知(新規askのみ確認)では今回の実害(新規に増えない古い滞留の見逃し)を再発させる。そのためStep 3では既読管理を持たず、毎回
status="open"の全件を読み直す設計にしている - 同型判定に閾値を埋め込まない: 「同型何件で起票するか」を機構側の固定ロジックにはしない。判断は都度LLM自身が行う
- SAは起動しない: 「読む→判断する→MCPツールを呼ぶ」だけで完結する軽量作業であり、実装コミットのような重い処理は発生しない。イベントを検知したセッション自身が判断から起票までを完結させる
- withdraw_ask・answer_ask・triage_askはこのループの対象外: 人間の裁定を待つ設計を崩さないため、これらのツールはask-watchからは呼ばない。トリアージ・回答済みのask個体は
statusがopenから変わるため、WHERE status='open'のポーリングでは元々検知対象に入らない - 重複起票防止はDBを正とする: state fileの
filed_meta_asksはあくまで人間向けの参考ログで、実際の重複判定は毎回get_asks(kind="meta")への問い合わせで行う。state fileが欠損・不整合になってもDB照会だけで正しく動く - withdraw等の代行はしない: Step 3の重複確認でpromoted済みの型に該当するopen askを見つけても、このスキルはそれを自動withdrawしたり自己裁定したりしない。観察として短報に記載するに留める
- メタask自体もactivityを止める: メタaskはトリガーとなった同型askと同じblocksを引き継ぐため、同じactivityに対して判断待ちが複数件(トリガーask+メタask)積まれる形になる。これは意図的な設計だが、運用上の観察対象でもある。open ask件数が単調増加するようなら、ask-watch側ではなく運用ルール側の見直しをユーザーに相談する
- Monitorは30分で自動失効する:
timeout_msの上限は1800000ms(30分)で、これより大きい値を渡しても30分に切り詰められる。継続監視には失効の都度Step 2の要領での張り直し(re-arm)が要る。加えてMonitorはセッション内蔵ツールのため、セッションが終了すると監視も終了する。長期運用は別途/scheduleでのクラウド化を検討(今回のスコープ外)
関連
ask-distillskill:add_askのレスポンスに含まれるsimilar_asksを見て、新規ask投稿のその場で同型の反復に気づいたときにメタaskを起票する。ask-watchは同じメタask起票の仕組みを、定期的な読み返しというもう一つの気づきの経路として補う。両者は排他ではなく、どちらの経路で気づいてもメタask起票のロジック(Step 4の組み立て方)は共通calm:manskill: ask storeの使い方そのものの説明
audit
過去判断の正当性を疑い、一次資料 + 経緯 log で全体像を再構成し、文脈不足を分析した上で、再発防止の知識を正しい場所に pin する 1 サイクル。retract / supersede の直接実行は audit 範囲外で、decision 改訂提案として material に書き、ユーザー裁定経路へ降ろす。
「長いけどここまでしないと一生同じところでグルグルする」が本 skill の存在理由。各ステップは「飛ばさない」ことを優先する。
役割範囲
| 項目 | 内容 |
|---|---|
| 配置 | skills/audit/SKILL.md |
| 発動セッション | main / orch (思考の発端側) |
| 対象 | 過去 decision / 設計判断 / 同 tag の方針推移 (1 audit = 1 主題) |
| 種別 | 自律発動スキル |
| 重さ | 長プロセス (1 audit ≈ 1 セッション内、複数ターン消費) |
適用範囲
このスキルは初回 load 時に発動するが、トリガー判定は本セッション内のすべての後続ターンに適用される。以降のターンで T-A1〜T-A5 / T-B1〜T-B3 に該当する出来事が起きたら、明示的に skill を再発動せずとも本書の起動時確認フロー (§ 起動時確認フロー) に自動で入る。
ただし「同主題 24h 以内 audit 済」(T-C2) を確認したうえで、重複 audit は走らせず前回 material を参照する。判定方法は § 重複防止 を参照。
decisionのretract / supersedeは、本スキルを経由せずに直接提案しない。改訂はdecision改訂提案としてmaterialに書き、ユーザー裁定の経路へ降ろす。
トリガー
T-A: 自発トリガー (claude 側状況認識)
| # | トリガー | 量の目安 | 判定根拠 |
|---|---|---|---|
| T-A1 | 過去 decision を引用して新規 decision 出した直後、引用元と整合か怪しいと感じた | 1 回でも | 引用整合性 |
| T-A2 | 同一 tag で 3 件目の方針変更が検知された (supersedes / [議論中] 含む) | 3 件以上 | グルグル防止 |
| T-A3 | 議論で「あれ、これ前にも議論したような…」状態 | 1 回でも | 既決見落とし救済 |
| T-A4 | 同じバグ・症状を 2 回以上目にした (構造問題の疑い) | 2 件以上 | 構造問題検知 |
| T-A5 | 設計レビューで「この案前回却下した気がする」と感じた | 1 回でも | 既決見落とし救済 |
T-B: ユーザー起点トリガー (発話ニュアンス検知)
| # | 発話例 |
|---|---|
| T-B1 | 「これ前に決めなかったっけ?」「また同じ話してる」「またこの話か」 |
| T-B2 | 「過去の情報・自分の知っている情報と矛盾してない?」 |
| T-B3 | 「グルグル回ってない?」「ちゃんと過去の議論を踏まえてる?」 |
T-C: 発動しない条件 (誤検知抑制)
| # | 状況 | 理由 |
|---|---|---|
| T-C1 | 設計議論中で挙動が固まっていない論点に対する自発発動 | 「方針変更」ではなく「探索中」 |
| T-C2 | 同 audit を 24h 以内に同主題で実行済み | 重複 (前回 material を参照すべき) |
| T-C3 | ユーザーが「audit はいい、進めて」と明示拒否した直後 | 明示否認尊重 |
| T-C4 | スコープが他 topic 管轄の仕組みのバグ観察である | audit の対象外 (委譲先 skill は無い) |
| T-C5 | 単発の新事実で decision/habit/tag-notes の前提が消えたとわかっている (再発や構造的パターンの疑いが無い) | 個別の撤回判断に留まるため forget skill の責務 |
起動時確認フロー
自発発動時 (T-A 系)
冒頭で以下を必ず提示し、ユーザー承認を取ってから本体プロセスへ入る:
[audit] 過去判断の正当性を疑う状況を観察:
- 発端: (T-A1〜T-A5 のどれが立ったか + 観察内容を 1-2 行)
- 想定対象: (audit 対象の decision / 設計テーマ / 同一 tag の方針推移の要約)
- 想定所要: 本セッション内で約 N ターン
audit を始めていい?
- A: 始める
- B: 後で / 今は不要
- C: スコープ調整して (対象を絞る・広げる)
A/B/C 形式で明示。B 選択時は何も記録せず終了 (空 audit 抑制)。C 選択時はスコープ調整→再確認→A。
ユーザー起点 (T-B 系)
確認スキップで Step 1 (発端の明文化) から入る。発端の明文化時にユーザー発話を原文引用する。
重複防止
Step 2 (スコープ確定) の前に必ず以下を実行:
search(keyword=主題キーワード, tags=["audit"], entity_type="material", limit=5)
- 24h 以内に同主題の audit material が hit → T-C2 重複と判定し、ユーザーに前回 material を提示して新規 audit は走らせない
- 同 tag の note 末尾に
#audited-YYYY-MM-DDハッシュタグマーカーがあれば、その日付が 24h 以内かもチェック - 該当なし → Step 2 へ進行
長プロセス手順 (7 ステップ)
Step 1: 発端の明文化
何が audit のきっかけか、claude が認識した状況・ユーザーが表明した疑問を原文で記録する。後のステップで「想定 vs 実態のズレ」を測る基準線になる。
- 自発発動 → T-A 番号 + claude 観察内容
- ユーザー起点 → T-B 番号 + ユーザー発話の原文引用
Step 2: 対象スコープの確定
audit する主題 (decision 1 件 / 設計テーマ / 同 tag の方針推移) を 1 つに絞る。複数主題は別 audit に分割。
- スコープ単位の例:
D#XXXX 単体,domain:calm × tag:HintServiceの方針推移,topic#464 内の P2 関連 decision 群 - スコープ広すぎ防止: 「1 audit = 1 主題」原則。複数論点が絡む場合は親 audit + 子 audit の分割を提案
Step 3: 一次リソース取得
対象主題に関連する一次資料を集める。順序は固定:
- 対象 decision の本文:
get_by_ids(items=[{"type":"decision","id":...}]) - 対象 decision の supersedes チェーン:
get_map(entity_type="decision", entity_id=..., max_depth=3)で前後関係 (relation_type=supersedes フィルタが効くなら活用) - anchor 参照先: 該当 decision を pin している material (
search(tags=["anchor", domain_tag])) があれば取得し anchor 対応表の検証先を読む - コード anchor: 「実装済」anchor のコードパスを
Readで確認 (variable / function 名でgrep補完)
「最新 decision を静的参照」は不可 (recompose-context の anchor確定手順の「anchorの型」と整合)。
Step 4: 関連 log の一通り読み (経緯把握)
get_logs(entity_type="topic", entity_id=...) + search(keyword=主題キーワード, entity_type="log", tags=[domain_tag]) で経緯 log を取得し時系列で読む。N 件・time-window 上限を設けて爆発を防ぐ:
- 上限: 直近 30 件 / 90 日 のいずれか狭い方
- 読む観点: 「誰が・いつ・どんな状況で・なぜ判断を変えたか」「却下案の理由」「再開ループの兆候」
Step 5: 全体像の整理 + 文脈不足の分析
ここが audit のコア成果。Step 3-4 を踏まえて以下を組み立てる:
5-a. 経緯マップ (時系列)
- YYYY-MM-DD: 初出 (D#A) — 動機: ... / 制約: ...
- YYYY-MM-DD: 方針変更 (D#B が D#A を supersede) — 動機: ...
- YYYY-MM-DD: 再変更 (D#C) — 動機: ...
- 現在: D#C が活きている / D#A・D#B は supersede 済 / 議論中: D#?
5-b. 論点の進化
論点が「同じ問い」を繰り返しているか、「新しい問い」が積み上がっているかを判別する。同じ問いの繰り返しが見えたら「グルグル」のサイン。
5-c. 文脈不足の分析 (audit の真の付加価値)
判断がブレた原因を構造で語る。例:
- 「制約 X (cwd / 環境 / 上位仕様) が議論時点で把握されていなかった」
- 「同 domain の既決 D#Y を見落とした」
- 「decision 文面が抽象的で再解釈の余地を残した」
- 「anchor が古く、検証ができない状態だった」
- 「議論時点の前提が事実上覆っているのに decision が retract されていない」
「ブレた」だけで終わらせず、次回ブレないために何が必要か (anchor 強化 / tag note 追加 / habit 化 / 単発 decision 追加) まで一段踏み込む。
Step 6: 検証結果の material 化
ここまでの分析を add_material で保存する (フォーマットは § audit material のフォーマット で詳述)。タイトル + content + tags + related を整える。
Step 7: 知識の pin 先選定 + 実行
Step 5-c で出た「次回ブレないための知識」を、§ pin 先判定マトリクス に従って配置する。
- 自律実行 OK:
add_pin/ tag noteupdate_tag/ materialadd_material/ habitadd_habitの追加系 - ユーザー裁定経由: 既存 tag note の 書き換え (削除側) / habit の 書き換え / decision の retract 提案
実行後、変更内容を audit material の ## 知識の pin 先選定 セクションに記録する (どこに何を pin したかの台帳)。
Step 7 完了後: 完了マーカー
audit 主題に対応する代表 tag の tag note 末尾に #audited-YYYY-MM-DD ハッシュタグマーカーを追記する。24h 重複防止 (T-C2) の判定に使う。この追記で天井 (4,000字) を超える見込みなら拒否される (§ 判定フロー Q2 直後の注記参照) ため、超える見込みなら先に demote_tag_notes で縮めてから追記する。
update_tag(tag="<代表tag>", notes="<既存notes>\n\n#audited-2026-06-22")
複数 tag に跨る audit の場合は、主題を最もよく代表する 1 つの tag にのみマーカーを書く (全 tag に書くと汚染が広がる)。
audit material のフォーマット
タイトル規約
audit: {主題の要約} ({YYYY-MM-DD})
主題が単一 decision なら audit: D#XXXX 正当性検証 (...)、設計テーマなら audit: HintService × consistency_check 分離経緯整理 (...) の形。
tags
必須: audit, reconsider, domain:<domain>, intent:audit
intent:audit は専用 intent タグ。これに紐づく tag note が audit セッション中の振る舞いルール (decision 即時改訂禁止 / 中断時の下書き保存 / pin 先判定マトリクス遵守 / 完了マーカー) を session に注入する。
source
audit skill 自発発動 (T-AX) / ユーザー起点 (T-BX) — 発端: ...
skill 経由で生成されたことを明示。後で audit material を集計するときに source キーで弾ける。
content セクション構成
## 発端
(T-A* / T-B* + 観察内容 or ユーザー原文引用)
## 対象スコープ
- 主題: ...
- 対象 entity: D#X, D#Y, A#Z, ...
- 関連 tag: ...
## 一次リソース
- decisions: D#X (本文要約), ...
- supersedes チェーン: D#X → D#Y → D#Z
- anchor 参照先: M#A (anchor 対応表 N 行目)
- コード: src/services/foo.py:bar
## 関連 log (経緯)
- L#A (YYYY-MM-DD): ...
- L#B (YYYY-MM-DD): ...
(時系列、上限 30 件 or 90 日)
## 全体像
### 経緯マップ
(Step 5-a 形式)
### 論点の進化
(同じ問い / 新しい問い の判別)
## 文脈不足の分析
(Step 5-c の構造分析)
## 検証結果
| 対象 | 判定 | 理由 | 改訂提案 |
|---|---|---|---|
| D#X | 維持 | ... | なし |
| D#Y | 文脈不足のため再表記推奨 | ... | retract→新規 / 本文加筆 / anchor 設定 |
| D#Z | 撤回候補 | ... | retract 提案 (ユーザー裁定) |
## 知識の pin 先選定
- tag note `domain:calm` に追記: ...
- habit 提案: ...
- anchor 追加: M#A の anchor 対応表に N 行追加
- 新規 material: 該当なし (or M#B 作成)
## 完了マーカー
- 対象 tag: `<tag>` に `#audited-YYYY-MM-DD` 追記済
## 残課題
- (次の audit / 議論で扱うべき論点)
- (フォローアップ activity 候補)
related (relations)
- 対象 activity (本 audit を呼んだ activity)
- 対象 decision / log
- 既存 audit material (再 audit の場合は前回 material と
related) - 対象 topic
サイズ予算
上限なし。audit は長プロセスで詳細記録が価値。audit material は check-in 注入ではなく search hit 経由なので、recompose 統合 material と違ってサイズ予算の継続コストは低い。
中断・再開
1 セッション完走前提だが、中断時は audit material を「下書き」状態で保存し、再開時は前回 material を update_material で更新する。tag note intent:audit にこの方針を注入する。
content 冒頭に **ステータス: 下書き (Step N で中断)** を明記して中断点を残す。
pin 先判定マトリクス
Step 7 の核となる判定。「正しい場所」とは、知識を再利用するときに最も自然に出会える場所。
4 候補の責務
| 永続化先 | 適用範囲 | 注入契機 | 更新コスト | 容量 |
|---|---|---|---|---|
| tag note | 特定 tag を持つ entity に遭遇したとき | tag が活きるセッションで自動注入 | update_tag で上書き | 中 |
| habit | 全セッション横断、tag 非依存 | ~/.claude/rules配下の自動生成ファイルで配信(trigger_mode='always'は全文、'intelligently'はタイトルのみのマニフェスト) | update_habit で上書き、ユーザー承認必要 | 小 (件数制限) |
| anchor (material 内) | 特定合意の真偽判定先 | recompose-context 経由 or 個別 audit で参照 | recompose-context で再生成・更新 | 大 (material 単位) |
| material (新規 audit 結果) | 経緯・調査結果そのもの | search hit / 関連 entity 経由 | update_material で上書き | 大 |
| (参考) decision | 単発の合意事項 | get_decisions / search hit | 直接更新不可 (新規 + supersedes) | 小 |
判定フロー (claude 内部判定)
Q1: その知識は特定 tag に紐づくか?
YES → Q2 へ
NO → Q3 へ
Q2: その tag の note は既に類似ルールを持つか?
YES (類似ルール改訂) → tag note (update_tag)、ただし削除/書き換えはユーザー確認
NO (純粋追加) → tag note (update_tag)、自律実行可
※ Q2 のどちらの分岐も、書き込み前に「追記後(マージ後)の notes が天井 (4,000字)
を超えるか」を見積もる。天井は「新しい長さが4,000字を超え、かつ既存より増加して
いる」書き込みのみを拒否するため、対象タグの notes が現在は天井未満でも、この
追記で超える見込みなら書き込みは拒否される。超える見込みなら先に `demote_tag_notes`
で該当セクションを資材へ退避し、返り値の `notes_length.over_budget` が `false` に
なったことを確認してから書き込む。この見積もりは Step 7 完了後に追記する完了
マーカー (`#audited-YYYY-MM-DD`) にも同様にかかる (マーカーの追記も notes を
伸ばす書き込みのため)。
Q3: その知識はセッション横断で常時想起されるべきか?
YES → habit、ただし新規 habit はユーザー承認必須
NO → Q4 へ
Q4: その知識は「合意の真偽判定先」(anchor) か?
YES → anchor (recompose-context 連携)
NO → Q5 へ
Q5: その知識は経緯・調査結果そのものか?
YES → material (audit material 自体に収まる、別途追加 material 不要)
NO → 単発合意 → decision 改訂提案 (ユーザー裁定経由)
自律実行レーン vs ユーザー確認レーン
| アクション | レーン |
|---|---|
| tag note への純粋追記 (既存削除なし) | 自律 |
| tag note の書き換え / 削除 | ユーザー確認 |
demote_tag_notes (天井超過タグのnotes縮小、mode="pointer") | 自律 (退避+ポインタ残しのため) |
demote_tag_notes (mode="drop"、ポインタも残さない) | ユーザー確認 |
| 新規 habit | ユーザー確認 |
| 既存 habit の更新 | ユーザー確認 |
| material 新規 (audit material 自体) | 自律 |
| material 更新 (anchor 対応表追加など) | 確証あれば自律 |
| anchor 新規/更新 | recompose-context の anchor確定手順 |
| decision retract / supersede 提案 | ユーザー裁定経由 (audit material に「提案」として記載のみ) |
add_pin | 自律 (純粋追加のため) |
remove_pin | ユーザー確認 |
完了マーカー (#audited-YYYY-MM-DD の追記) | 自律 (純粋追加のため) |
生成成果物
必須成果物
| 種別 | 件数 | 内容 |
|---|---|---|
| audit material | 1 件 | § audit material のフォーマット |
| log (audit セッションの経緯) | 1 件 | recording skill 経由 |
| 完了マーカー | 1 件 | 対象代表 tag note に #audited-YYYY-MM-DD 追記 |
条件付き成果物
| 種別 | 条件 | 内容 |
|---|---|---|
| pin (tag → material) | 主題の代表 tag が決まり、anchor 化が必要な場合 | add_pin(source_type="tag", ...) |
| tag note 更新 | tag note に書くべき横断ルールが新たに見えた場合 | update_tag(notes=...) |
| habit 追加 | tag 非依存の行動ルールが見えた場合 | add_habit(...) (ユーザー承認後) |
| decision 改訂提案 | 既存 decision を retract / supersede すべきと判断した場合 | audit material 内 ## 検証結果 テーブルに「改訂提案」として記載 (直接 retract はしない)。頻繁に参照されるのに定型節(書式は本スキル同梱の references/precedent-format.md)が無い decision に遭遇した場合は、supersede 再記録時に定型節(特に却下案・検証)付きの reason で書き直すことを提案に含める。単純な retract は却下理由・射程の情報を失うため、頻出参照の decision は supersede を優先する |
| 新規 activity 起票 | フォローアップ作業が必要な場合 | add_activity(intent:implement / discuss) |
関連 skill との境界
対比表
| 軸 | audit | recompose-context | postmortem |
|---|---|---|---|
| 動機 | 過去判断の正当性疑い | 累積情報の整理 | completed activity の振り返り |
| 対象スコープ | decision / 設計テーマ / 同一 tag 方針推移 | activity / topic / decision (関連グラフ全体) | 完了 activity 1 件 |
| 入口 | 自発トリガー T-A* / ユーザー T-B* | 手動 (「/recompose」「整理して」) or hint 誘導 | 手動 (「/postmortem」or activity 指定) |
| 出力 | audit material + pin 群 + 完了マーカー | 統合 material + anchor 対応表 + リコンサイル | 反省ポイント material + 教訓永続化 |
| 重さ | 長 (1 セッション級) | 中 (整理単位次第) | 中 (ステップ分解 + 対話) |
重なる動作の役割分担
| 動作 | 第一責務 | audit との関係 |
|---|---|---|
| 一次リソース取得 | recompose-context | audit も実施するが「過去判断の妥当性」の観点で読む (recompose は「最新統合」の観点) |
| anchor 設定 | recompose-context | audit が anchor 不在を発見したら recompose-context の anchor確定手順を使う |
| 経緯 log 整理 | recompose-context / postmortem | audit は経緯を「ブレの原因分析」目的で読む (postmortem は「行動ステップごとの教訓抽出」) |
| 知識の pin (tag note / habit / anchor) | audit (固有) | recompose-context は anchor 対応表のみ更新、その他 pin 先選定は audit が担う |
| decision 改訂提案 | audit (固有) | retract/supersede は audit からの「提案」止まりで、決定はユーザー裁定 |
起動順序 (典型シナリオ)
- 「decision 引用時に怪しい」→ audit (自発 T-A1) → audit 中で anchor 不在判明 → recompose-context の anchor確定手順
- 「topic#X 全体を整理したい」→ recompose-context → 統合中にズレ発見 → audit を提案
- 「completed activity の振り返り」→ postmortem → 反省ポイントから知識永続化先迷う → audit の判定マトリクス参照 (任意)
HintService との境界
audit skill は HintService (src/services/hint_service.py) とは経路と重さが完全に分離された設計。両者は同じ「過去判断との整合」関心領域だが、相互呼び出しはしない。
| 軸 | HintService | audit skill |
|---|---|---|
| 仕組み | 軽量 hint (info/warn) を hint type 値域から生成 | 長プロセス skill (人間対話 + 思考) |
| consistency_check | type 値域から削除済 | audit skill が代替担当 |
| 発火経路 | check_in 同期 / Stop hook 経由 additionalContext | description トリガー + ユーザー発話 |
| 永続化 | hint type 表現 + tag note 内ハッシュタグマーカー (#audited-YYYY-MM-DD 等の suppress 用途) | audit material + 各種 pin |
| severity | info/warn のみ (block 不採用) | severity 概念なし (skill は手続き) |
完了マーカー #audited-YYYY-MM-DD は HintService 側 hint 重複抑制と共通の仕組みを意図しているが、audit skill 自身の 24h 重複防止 (T-C2) の判定にも使う。
Edge Cases
| ケース | 期待挙動 |
|---|---|
| audit 対象 decision が retract 済 | audit material の ## 検証結果 に「対象は既 retract」と記録し、supersede 先の決定が今も妥当かを副次 audit |
| 対象 topic が他セッションで並行修正中 | 並行修正の log を Step 4 で拾い、現在 in-flight な議論を ## 残課題 に明示 |
| 一次リソース (コード) が存在しない (anchor リンク切れ) | ## 文脈不足の分析 に「anchor が剥がれている」と記録し、anchor確定手順の対象としてマーク |
| 「過去 decision を引用」した直後で実際にはマッチしていた (T-A1 誤検知) | Step 1 の発端明文化時点で「マッチ確認済」と書き、Step 2 でスコープなしとして audit 中断 (空 audit) |
| ユーザーが Step 5 途中で「もういい、わかった」と中断 | 部分的な audit material を「下書き」として保存 (§ 中断・再開) |
| audit を recompose-context が呼んだ場合 | recompose 中の発見 (ズレ・矛盾) を発端として audit に降ろす経路は OK。audit 完了後に recompose に戻る |
| skill 実行中 (他 skill 実行中) に audit トリガー | 現在 skill 完了まで待ち、終了後に audit 起動。skill 入れ子は禁止 |
| 同 decision を 2 回 audit (T-C2 抜け) | T-C2 重複検知が漏れた場合は Step 2 (スコープ確定) で前回 material を発見し、重複と判定して ## 残課題 引き継ぎのみで終了 |
| HintService 側で consistency_check 完全削除済なのに過去の hint 残骸が見える | 残骸を発見したら report_signal(CALM 自身の故障報告、kind の全種定義は report_signal ツールの docstring を正とする)で報告する (audit の範囲外) |
| 完了マーカー追記対象の tag が複数候補ある | 主題を最もよく代表する 1 つの tag にのみ追記 (全 tag 汚染回避) |
board
Claude同士の非同期のやり取りに使う掲示板の使い方をまとめる。掲示板の実体は新設のテーブルではなく、CALM既存のトピック・ログへの相乗り。
発動契機
以下のいずれかに該当する場合に発動する。
- 掲示板トピックへ投稿しようとしている場面(質問・周知・意見募集・事前の声かけ)
- 意見募集のために議論用トピック・[議論]アクティビティを新しく立てようとしている場面
- ユーザーが「他のセッションに聞いておいて」「非同期で周知しておいて」「意見をもらっておいて」「触る前に衝突がないか確かめておいて」のように、非同期の発信を明示的に指示した場面
対象外
- 相手セッションが今生きていて、すぐ返事が欲しいとき: 掲示板を使わず、セッション台帳の宛先候補にSendMessageで直接話しかける(ListAgentsや
get_sessionsで相手を見つける) - 作業の依頼、着手の表明: 依頼は作業の実行体制の管轄、着手の表明はcheck-inとセッション台帳で分かるため、どちらも掲示板の対象外
- 人間への判断委譲:
ask-composeが担当する
投稿前に検索する
掲示板に書く前に、その内容がすでに記録(decision・log・material)で答えが出ていないかをsearch等で確かめる。既存の記録で答えが出る質問を掲示板に流さない。
フィードバック機構との違い
宛先を名指ししない質問と、それへの答えも、フィードバック機構ではなく協力機構(この掲示板)側の使い方である。フィードバック機構は「いま書いたことが後で条件に当たったときに効く」時間軸の仕組みで、掲示板は「いま並行して動いている相手と交換する」空間軸の仕組み。両者を混同しない。
掲示板トピックの目印
掲示板として使うトピックには、素タグ board(名前空間なし)を必ず付ける。domain:など既存のタグに追加する形で付ける。
掲示板トピックを見つける・作る
どの使い道でも、投稿する前にまずこれを行う。
- 元のトピックに関連する掲示板トピック(
boardタグ付き)がすでにあるかを確認する(元トピックの関連やsearchで見つかる) - 無ければ
add_topicで新規に作る。related引数で元のトピックを同時に関連付ける(作成と関連付けを1回で行えば、「関連付けてから投稿する」が自動的に守られる)。タグにはboardを必ず含める
質問・周知・事前の声かけは、掲示板トピックが用意できればそこへの投稿で足りる。議論用の[議論]アクティビティとgoalを追加で立てるのは、次々節「議論を立てる」の条件に当たる意見募集のときだけ。
非同期の使い道は4つ
作業の依頼と着手の表明はここに含まれない。
質問
困っていることを書き、知っている(かもしれない)セッションに答えてもらう。
CALMのaskには「答える相手」(human/claude)を区別する列がまだ無い。区別できるようになるまでは、Claude宛ての質問をaskに混ぜない。add_askは人間への通知(LINE・ダッシュボード等)を伴うため、Claude同士の質問を混ぜると人間の判断待ちの受け箱が埋まるため。当面は、質問も掲示板トピックのログに書く。
投稿する前に必ず「投稿前に検索する」を確認する。返事の待ち方は後述「返事を待つ間」を参照。
周知
前提の変化を、関係するセッションに知らせる。答えを待たない。
掲示板トピックのログに書く。宛先が分かるなら(書き込みの応答に宛先候補が付いていればそれを使う。付いていなければListAgentsやget_sessionsで探す)、SendMessageで直接知らせる。
並行セッションが同じ作業に気づかず重複して着手する事故は、周知で防げる典型例。共有ファイルやアーキテクチャの前提を変えたときは、周知を検討する。
意見募集
自分の設計・判断を、別の文脈にいるセッションに見てもらう。
その場の1往復で済まない、または相手が今生きていない場合は、次節「議論を立てる」の手順で議論トピックを立てる。それ以外(相手が今生きていて1往復で済む)なら、掲示板を使わずSendMessageで直接聞く。
事前の声かけ
共有物(README、共通のドキュメント、複数セッションが触りうるファイルなど)を触る前に、他セッションとの衝突がないかを確かめる。
相手が今生きているなら掲示板を使わずSendMessageで直接確認する。生きていない、または関係するセッションが複数いて把握しきれないときは、前節の掲示板トピックに書いておく。
議論を立てる
意見募集で、次のどちらかに当たるときだけ議論トピックを立てる。
- 相手が今生きていないとき
- 往復が1回で済まないとき
立てるのは意見を求める側のセッション自身。自動で立てるきっかけは作らない。前節「掲示板トピックを見つける・作る」で掲示板トピックを用意したうえで、次の3つを行う。
- [議論]アクティビティを立て、goalを付ける。
activity-start経由で立て、関連に前節の掲示板トピックを含める(参加者が同じトピックへcheck-inできるようにするため)。goalの条件は真偽の付く1文で書く(例:「論点Xについて決定事項が記録された」)。議論が長引いて収束しない場合に備え、打ち切りの条件も持たせる - 最初の投稿をする。 投稿は掲示板トピックへのログ追加。書き方は後述「投稿の書き方」に従う
- 参加者を呼ぶ。 ListAgentsや
get_sessionsで相手を特定し、SendMessageで議論用アクティビティ(参加者がcheck-inする先)を伝える。相手が今動いていないセッションで、新しくbg(claude --bg)を立てて呼ぶ必要があるときは、それができるのは人間と直接話している窓口のセッションだけ。自分がその窓口でなければ、人間に立ち上げを頼むか、窓口セッションに依頼する
議論の結論は、議論用トピックではなく元のトピックにdecisionとして書く。議論用トピックは経過(生の往復)を残す場所であり、決定の正本ではない。
返事を待つ間
掲示板トピックへの投稿は、今の差分通知の仕組みでは相手に自動的に届くとは限らない。待機中のセッションを実際に起こせるのはSendMessageだけなので、質問や議論で相手の反応を待つときは、投稿のたびに宛先へSendMessageで知らせる。宛先の見当が付かない場合は、投稿だけして相手が気づくのを待つ(気づかれない可能性がある)。
投稿の書き方
- 投稿は掲示板トピックへの
add_logs - タイトルの先頭に投稿者のセッション名を角括弧で書く(
get_sessionsで分かる自分の行のalias(別名)を使う。alias未設定でもget_sessionsは自動生成された別名を返すため、常にaliasを使う。ListAgentsの生の自動生成名(get_sessionsのname)をそのまま貼らない)。誰の発言か記録から追え、相手がそのままSendMessageの宛先として使える名前にするための規約
参加するとき
自分宛てではない議論に後から参加する、または周知を読みに行くときは、掲示板トピックを関連に含むアクティビティへcheck-inしてから参加する。自動的な差分通知だけに頼らず、気になる掲示板トピックがあれば待たずにget_logsで直接読みに行く。
recording / decision-recordとの境界
- 掲示板への投稿は
add_logsを使うが、目的は自分の作業の経緯や成果物の記録ではなく他セッションへの伝達なので、recordingスキルの対象外として扱う - 議論の結論をdecisionとして記録するときは、
decision-recordスキルの合意判定基準に従う(掲示板上の合意だけで自動的にdecisionにはしない)
check-in
指定されたアクティビティに対して check_in ツールを呼び出し、関連情報を調べてアクティビティの全体像と進捗を把握してください。check-in後にユーザーが「やって」と言えばすぐ作業・議論を開始できる状態にすることがゴールです。
関連skillとの境界
- 新しい作業を始めるときはactivity-startの担当。check-inは既存アクティビティの再開(「前回の続き」等)に使う
- 期間を横断した振り返りはdigestの担当
手順
- 引数で
activity_idが指定されていればそのまま使う - 指定されていなければ、SessionStart hookが注入済みのアクティビティ一覧(
# アクティビティ一覧— 「作業中(別セッション)」「優先」の階層構成で、行は#NNN タイトルの形式)を使う。orchの子は親の行の下に✓ ▷ ◷ ✕(達成/着手できる/待ち/失敗、無印は動いている)の状態記号付きでぶら下がる a. この一覧はhookが決定論的に組み立てた表示用markdownであり、hook自身が「再フォーマットや優先順の再評価をせず、必要時はそのまま提示してください」と指示している。再構成・要約し直さずそのまま提示する。ここに現れる#NNNはタイトルに併記される形式であり、hookの指示に従いそのまま表示してよい b. 選びたいアクティビティがこの一覧に無い(末尾の「## 未表示」節に該当する、またはこのセッションでhookの出力を持っていない)場合はget_activities()でフラットに取得しフォールバック表示する。この場合はトピック名・アクティビティ名のみを提示し、IDは表示しない c. ユーザーが名前やキーワードで選択したら、対応するactivity_idでステップ3へ進む check_in(activity_id=...)を呼び出すanchor.activity.tagsにorchがあれば、そのアクティビティはorchである。以降の手順に進まず、その場でorch skillを発動して代わる節の手順(check_inは済んでいるので手順2から)で担い手を引き受け、まとめ役として再開する。orchの子になる作業を自分で始めてはならない
get_logs・get_decisions・searchなどで関連情報を取得し、概要と進捗を把握する- check-in結果に含まれるタグ一覧を見て、明らかな表記揺れや重複に気づいたらユーザーにサジェストする。分析ツール(
analyze_tags)は呼ばない - 把握した内容を以下の2セクション構成でユーザーに伝える
check-in結果は5つの枠(anchor/control/context/catalog/env)に分かれている。フィールドの正確なパス・出力の形はcheck_inツールのdocstringを正本とし、以下は扱い方の説明に留める。
anchor.pinnedフィールドの扱い
check-in結果に anchor.pinned フィールドがある場合、その内容はタスクに常に意識してほしい情報としてpinされたエンティティ群である。以下の5種が含まれることがある(0件キーは省略される):
anchor.pinned.decisions: 重要な決定事項(id, title, reason付き)anchor.pinned.logs: 重要な議事録・ログ(id, title, content付き)anchor.pinned.materials: 重要な参考資材(id, title, content, source付き)anchor.pinned.topics: 関連トピック(id, title)anchor.pinned.activities: 関連アクティビティ(id, title, status)
pinned情報は進捗把握の最初に確認し、概要・進捗の説明に反映すること。
truncatedフィールドの扱い
check-in結果に truncated フィールドがある場合、応答が全体予算を超えたため一部セクションが末尾やスタブへ切り詰められている。cuts の各要素の section はドット区切りの入れ子パス(例: anchor.pinned、catalog.map)で、next({tool, args} の形の続きへのポインタ)が付いていれば、そのツールをそのまま呼べば削られた分の本文を取り直せる。over_budget: true のときは全部を切り詰めてもなお超過している状態だが、それ自体はエラーではないので、必要な情報が足りないと感じた箇所だけ next で追加取得すればよい。
env.hintsフィールドの扱い
check-in結果に env.hints フィールド(文字列リスト)がある場合、それはタグに蓄積したdecisionの整理(recompose-context skill)をおすすめしたい状況を示すナッジである。出力の最後に、各hintの内容を「〜をおすすめします」程度の一言として添えるに留めること。check-inの目的(現在のアクティビティの進捗把握)を差し置いてrecomposeに着手してはならない。
control.asksフィールドの扱い
check-in結果に control.asks フィールドがある場合、対象アクティビティをblockしているaskが1件以上ある。awaiting_answerは回答待ち、awaiting_triageは回答済みだが未トリアージのask一覧である。awaiting_triageが1件以上あれば、triage_askでpromote/dismissへ振り分けること。moreとnextが付いていれば、件数分はまだ未取得なのでnextのツール呼び出しで残りを取得できる。
env.sessionフィールドの扱い
env.session.alias_collisionがtrueのときは、セッション別名が他セッションと衝突して付け替わった旨をユーザーに伝えること。
control.goalフィールドの扱い
check-in結果に control.goal フィールドがある場合、対象アクティビティの終了条件と次にやるべきこと1件(next)がまとまっている。goal.errorが入っていれば組み立てに失敗しただけなので無視してよい。labelに応じて次のとおり動く。
label: judge_ready(判定待ち):open_questionsに未決があれば畳むかユーザーに1ターン確認する。そのうえで、terminalの充足が1件以上あればjudge_goal(goal_id, verdict="achieved", note=...)、0件ならjudge_goal(goal_id, verdict="failed", note=...)をその場で呼ぶ。人間の判断は待たず、判定したことの報告もしないlabel: undefined(未定義):nextの文面どおり、真偽の付く終了条件が会話にある、または意図から推せるならset_goalで書く。ユーザーの追認は待たず、書いたことの報告もしない。候補が複数で定まらない、またはこの活動には終わりがあるはずだが何なのか推せないときだけユーザーに聞き、定まれば同様に書く。聞いても定まらない、またはそもそも判断材料が無いときは何もしないnext.ruleが13(外部待ちの再確認。確かめる主体はClaudeなのでnext.actorは常にclaudeになる):next.whatが示す条件を、ghなど実際の手段で確かめる。確認できたら該当条件をupdate_goalでsatisfiedにし、確かめた事実はadd_materialかadd_logsに残す。確認できなければ確認済みである旨だけをnoteに残してopenのまま待つnext.ruleが14(待ち。まだ再確認の時期に達していない): 会話や記録から満たされたと分かれば、確認や報告なしにupdate_goalでsatisfiedに書く。分からずnext.actorがhumanのときは、その場で聞ければ聞いて決定事項にする(回答が得られればdecision-recordの通常の流れで記録される)。聞けない、またはnext.actorがexternalなら、無理に確かめようとせずnext.whatをユーザーに一言伝えて待つlabel: closed(判定済み):last_verdictをユーザーに伝え、残作業が無ければupdate_activity(status="completed")で閉じ直す(closed_byは渡さない)- 上記以外(
next.actorがclaudeなど):next.whatが示す作業にそのまま取りかかる
label: judge_ready時の判定分岐(open_questionsの扱いからjudge_goalの呼び分けまで)は、recordingの「記録の直後にgoalの条件を満たす場合」節・decision-recordの「決定記録の直後にgoalの条件を満たす場合」節からも同じロジックとして参照される正本である。判定条件を変更する場合はこの節を更新の起点とし、他の2箇所の記述も同じ内容に揃える。
出力フォーマット
check-in: {anchor.activity.title}
## 概要
{タスクの背景・目的・やることがユーザーに伝わる程度にまとめる。anchor.activity.descriptionと関連情報をもとに構成する}
## 進捗
intent: {タグから抽出した intent 値、なければ省略}
{logs・decisions・materialsなどから読み取れる、実際にどこまで進んでいるか・何が残っているかの要約}
coding-project-setup
コードプロジェクトの知識フレームをセットアップする。project-setupのsub-skillで、プロファイリング済み(相手はエンジニア・目的は開発)を前提とする。ゴールは「次のセッションがcheck_in・searchで文脈を取れる状態」。既存mdの走査とインタビューは排他ではなく、同一フレームを埋める2つの充填手段。mdで埋まった項目はスキップし、穴だけ聞く。
発動の入口
原則としてproject-setup skillのプロファイリング(Step 1〜2)を経て委譲される。エンジニアのユーザーが直接頼んだ場合も発動してよいが、ペルソナがauto-memoryに無ければproject-setup側のプロファイリングを先に行う。
コードを扱わない取り組みのセットアップはproject-setupの職種中立経路の担当であり、本スキルは発動しない。
フレーム定義(最低限ここまで)
| # | 項目 | 落とし先 |
|---|---|---|
| F1 | プロジェクト識別子+一言説明 | domain:タグ新設 + notes(リポジトリのremote識別子を含む) |
| F2 | 関心事の初期素タグ 2〜4個 | 素タグ(固有概念にはdescription付与) |
| F3 | 既に決まっている大方針 | decision(ユーザー裁定を経て記録) |
| F4 | 進行中・直近やること | activity |
| F5 | 参照すべき場所 | domain/素タグのnotesに参照ポインタ(他マシン・他セッションから解決できるものに限る) |
F1のリポジトリ参照とF5の参照ポインタに書けるのは、remote URL・owner/repo形式の識別子・サービス名・リポジトリ内の相対パスなど、書いた本人のマシン以外からも解決できるものに限る。マシンローカルの絶対パス(~/・/Users/...)やユーザーレベル設定配下(~/.claude/等)は書かない。CALMの記録はcheck_inで他セッションのtag notesとして注入され、export等でpeerを超えて人に渡りうるため。ローカル固有の場所しか出てこなかった場合はF5を空のままにし、その情報を残す必要があれば remember の判定木へ流す(セットアップ独自の仕分けをしない)。
本skillが設計上あらかじめ落とし先を固定している書き込み(フレームF1〜F5)は、保存先が未確定の依頼を扱う remember の判定対象ではない。判定が要るのはフレームに収まらない知識のほうで、そちらは後述のとおりrememberの判定木へ流す。
タグは単独で新設できない。domain:タグ・素タグは、それらをtagsに載せたエンティティ書き込みで初めて実体化する。notes・descriptionの付与はその後段でしか行えない。
topicは中身が載るときだけ作る。中身のないtopicを儀式的に先に立てても検索・紐づけの足場にならない。本skillではセットアップの経緯ログとF3のdecisionが中身にあたるので、それらを載せる器としてこのセットアップを表すtopicを1件だけ作る。F3が空(decisionが1件も無い)でも経緯ログは残るのでtopicは作る。議論用のtopicを先回りで乱立させない(議論のtopicは議論が始まってから自然発生に任せる)。
手順
Step 1: domain確認
- ユーザーの発話・cwdからdomain名の案を作り、
search_tags(query=<候補名>, namespace="domain", include_notes=True)で既存タグを確認する。namespaceを絞らない・include_notesを省いた呼び出しでは判定材料(notes)が返らない - search_tagsはタグ名のLIKE一致とベクトル検索のハイブリッドなので、意味的に近いだけの別名タグも返る。衝突判定は返却された
nameの完全一致で行い、上位ヒットの有無では判定しない。usage_countは判定に使わない(retract済みを含む付与回数で、余談1件でもすでに1以上になるため区別できない) - 完全一致するdomain:タグが無ければそのままStep 2へ進む。ある場合は以下で分ける。
archived(検索結果の各タグに付くbooleanで、退役済みかどうかを示す)がtrueのタグも完全一致として扱い同じ分岐に入る(archivedの値で扱いが変わるのは最後の枝だけ)get_activities(tags=["domain:<名前>"], status="active")が1件以上返る → F4が埋まっており稼働中のフレームが既設。本skillの対象外なので、見つかったアクティビティ名を挙げてそのアクティビティへのcheck-inを案内して終了する(check_inはactivity_idが必要なため、案内は具体的なアクティビティを名指しする)- 0件なら
status="snoozed"・"shelved"・"completed"でも個別に呼ぶ。statusの既定値"active"はpending+in_progressしか返さず、全ステータスを一括で返す値は存在しないため、この追加呼び出しを省くと寝かせてある・終了済みのフレームを見落とす。1件以上返る → 過去にフレームが立っている(寝かせてある / 終了済み)ので、見つかったアクティビティを挙げ、そこへ合流するか・同じdomainで立て直すか・別名で新設するかをユーザーに裁定させる - どのステータスでもアクティビティが無く、
notesが空でない → 取得した既存notesをユーザーに提示し、別名で新設するか既存domainへ合流するかを裁定させる(合流する場合、Step 5のnotes書き込みは新規作成ではなくマージになる) - アクティビティも
notesも無い場合、archivedがfalseならそのまま続行してフレームを埋める(過去の言及だけでタグが実体化した状態)。archivedがtrueなら退役済みでフレームが立っているとは扱わない。同名で立て直すか別名にするかをユーザーに確認してから進む(別名にするなら新しい名前でこの確認をやり直す)
Step 2: md走査(読み取りのみ、何も変更しない)
- 対象: リポジトリ内でremoteから取得できるmd(README / docs/ / CONTRIBUTING / ADR / リポジトリのCLAUDE.md 等)
- 対象外: ユーザーレベルのローカルmd(
~/.claude/配下等)。CALMの記録はexport等でpeerを超えて人に渡りうるため、取り込み自体を避ける - フレームF1〜F5への充填案を抽出する。詳細情報は転記・再構造化せず、参照ポインタ(リポジトリ内パス・URL)として扱う
Step 3: 充填案の提示・裁定
- F1〜F5の充填案と未充填項目を1つの表にまとめて提示する
- 裁定の粒度を分ける: **タグセット(F1/F2)**はまとめて一括承認でよい。**decision候補(F3)**は1件ずつ中身を展開して個別裁定する。md由来の内容はユーザーが裁定して通せば合意扱いとし、どのmdのどの記述に由来するかを
reason本文の中に文章として書く(リポジトリ内の相対パスで示す。reason末尾の定型節に由来用の節は無いので、独自の見出し行を足さない) - タグ作成規律: 素タグは少なめに倒す(2〜4個目安)。ディレクトリ構造からの機械的切り出しはしない。description(100字以内の一言定義)を付けるのは「プロジェクト固有の意味・実体を指すタグ」のみ(造語・固有名詞・一般語の固有用法)。一般語彙タグには付けない。判定は「名前が読めるか」ではなく「このプロジェクト固有の意味か」で行う
Step 4: 未充填分の会話ヒアリング
- フォーム型の質問リストを提示しない。「一言で何?」「N個挙げて」のような要約・圧縮・選別の作業をユーザーに課さない
- 未充填項目を会話の流れに沿って聞く(例: F3が空なら「技術選定とかアーキテクチャでもう決まってることある?」、F4が空なら「直近は何から手をつける?」)
- ユーザーの自由な発話はmdと同じ充填材料として扱い、F1〜F5への構造化(一言説明の起草・タグ候補の抽出)はAIが行って案として提示・裁定を受ける
- 「わからない・まだ無い」は正当な回答。F1のみ必須、F2〜F5は空のまま進めてよい
- フレームに収まらない知識(規範・判断基準・手順・背景の生発話)は remember の判定木で置き場を判定する
Step 5: 書き込み実行
- 書き込みは2段構成。タグを実体化させるエンティティ書き込みが先、タグ属性(notes・description)の付与が後になる
- このセットアップを表すtopicを
add_topicで1件作る(title 35字以内、descriptionにセットアップの目的と範囲を書く)。tagsにはF1のdomain:タグとF2の素タグをすべて載せる。これがタグを実体化させる器を兼ねるので、素タグを載せ忘れると後段のdescription付与がNOT_FOUNDで落ちる - セットアップ実行の経緯を
add_logsで記録する(recording skillの基準に従う)。topic_idには1で作ったtopicを指定する - decision(decision-record skillの規律に従う。
topic_idは1で作ったtopic)→ activity(activity-start skillの規律に従う) - タグ属性を
update_tagで付ける: domain:タグのnotes、固有概念の素タグのdescription、F5の参照ポインタ(domain/素タグのnotesへ)。update_tagはnotesとdescriptionを同時指定できず、notesは全文置換なので、domain:タグのnotesは一言説明・リポジトリのremote識別子・参照ポインタをまとめた最終形を1回で書く。既存notesを持つdomain:タグへ書く場合は、Step 1のsearch_tags(include_notes=Trueで呼ぶ)で取得した既存notesを保持したままマージした全文を書く(全文置換なので、書かなかった内容は消える)
- このセットアップを表すtopicを
- mdの全文をmaterialに複製しない
Step 6: 結果報告
- 作成したフレームの一覧(タグ・decision件数・activity・ポインタ)を提示する
運用開始後の増分は対象外
会話中に未知のドメイン固有概念に遭遇したときのインタビューは、habit(未知概念インタビュー)が担う。本skillは初期一括のみ。
db-recovery
SessionStart hookが検知したDBデータ異常減少への自律復旧スキル。検知 → 確認 → 提示 → 承認 → 実行 → 再検証の順で進める。全自動実行はしない。実行前に必ずユーザー承認を取る。
発動契機
以下のいずれかで発動する。
- SessionStart hookがDB異常減少警告(🚨🚨🚨 DBデータ異常減少を検知)を注入した
- 会話中に、activity/decision/log等の想定件数の少なさや直近記録の消失に自分で気づいた
- ユーザーから「データ消えてない?」「件数減ってない?」と指摘された
以下では発動しない。
- 警告が無く、通常のDB状態である
- 直前の正当な操作(大量retract・tag-cleanup等)による説明可能な減少だと確認済みである
- ユーザーが既に別経路で復旧完了したと明言した
発動したら、異常警告を放置したり、calm:manの手動手順だけを案内して終わらせたりしない。
発動時の前提
hookの警告は _build_snapshot_section(hooks/session_start_hook.py)がSessionStartのadditionalContextとして注入する。警告本文には対象テーブルと減少件数(前回件数 → 現在件数 (-N件))が含まれる。このスキルはこの警告文を読み取るところから始まる。
復元本体(restore_snapshot)は以下を内蔵している。このスキルは重複実装しない:
- 復元前の現行DBの自動退避(
prerestoreスナップショット) - サーバー稼働中チェック(稼働中は
--forceなしで実行不可) - スナップショットの整合性検証(
verify_snapshot) - schema互換性チェック(巻き戻し疑いは
--yesなしで実行不可)
手順
1. 異常確認
- hook警告本文をパースし、どのテーブルが何件減ったか(
discussion_topics/decisions/discussion_logs/activities/materials)を把握する - 現在のDB状態を実際にクエリして裏取りする(
get_activities/get_decisions等のCALMツール、またはuv run --directory "${CLAUDE_PLUGIN_ROOT}" python "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.py" listで分かる直近の行数)。警告は前回スナップショット取得時点との差分であり、直近の正当な操作(大量retract・tag-cleanup等)による見かけ上の減少でないか確認する - 確度を判定する:
- 明確な異常: 直近セッションで該当テーブルへの意図的な大量削除・retract操作の記憶がない
- 説明可能: 直近でtag-cleanup・大量retract等の正当な操作があったことが会話履歴やlogから確認できる
- 不明: 判断材料が無い
2. スナップショット所在確認
uv run --directory "${CLAUDE_PLUGIN_ROOT}" python "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.py" listで全kind横断の一覧を取得する- 各エントリの
kind/created_at/db_size_bytes/quick_checkを確認する。quick_checkがok以外のものは復元候補から除外する - 異常検知直前(=データがまだ健全だった時点)に最も近いスナップショットを候補として特定する
- 補足:
_build_snapshot_sectionは異常検知時(is_healthy=False)に新規periodicスナップショットの取得をスキップする実装のため、異常検知セッション中に直前の健全世代が壊れたスナップショットで上書きされることはない
3. 復旧方法の提示
ユーザーに以下をA/B/Cの選択肢として提示し、承認を取る。承認なしに実行しない。
[db-recovery] DBデータ異常減少を検知:
- 対象テーブル: (例: decisions: 1200 → 1050 (-150件))
- 確度: (明確な異常 / 説明可能 / 不明)
- 復元候補: (スナップショットのcreated_at / kind / パス、quick_check結果)
復旧方法を選んでください:
- A: 最新スナップショットから全体復元 — 復元後、復元時点以降に記録した内容は失われる
- B: 部分復元(特定テーブルのみ、または欠落範囲を特定して手動補完)— backup_serviceはテーブル単位・行単位の部分復元を自動化していないため、実質SQLレベルの手動作業になる。工数とリスクを明示した上で提案する
- C: 復旧せず先に進む(誤検知と判断、または復元コストが見合わない場合)
- 各選択肢について「何が起きるか」「何を失うリスクがあるか」を必ず併記する
- A/Bは「MCPサーバーの停止が必要」という制約を必ず明示する(
restore_snapshotは稼働中サーバーに対して--forceなしでは実行できない)。--force/--yesを自発的に付けて安全装置を回避しない
4. 承認後の実行(Aを選んだ場合)
- サーバー停止・復元を一連の操作として承認を取る。「復旧していい?」への直接的なyes/noが必要(「任せる」等の一般的信任表明では実行しない)。この承認は停止・復元までを対象とし、再起動は含まない(下記6.で復元結果提示後に別途承認を取る)
- サーバーを停止するとMCP接続が切れて記録できなくなるため、停止前に現状(検知内容・確度・提示した復旧方法・ユーザーが承認した内容)を
add_logsで記録する uv run --no-sync --directory "${CLAUDE_PLUGIN_ROOT}" python "${CLAUDE_PLUGIN_ROOT}/scripts/restart_server.py" --stopでサーバーを停止する(接続中のブリッジプロセスは巻き添えにせずLISTEN中のプロセスだけを狙って止める)uv run --directory "${CLAUDE_PLUGIN_ROOT}" python "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.py" restore --latest(Step2で特定した候補が最新でない場合は該当パスを直接指定)を実行する復元エラー: サーバーが稼働中のため復元を中断しましたが返った場合、上記3.(サーバー停止)が漏れている。サーバー停止を再確認してからリトライする- schema互換性警告(
--yesを要求するメッセージ)が出た場合は、警告文をそのままユーザーに見せて--yes付き再実行の可否を確認する。自己判断で--yesを付けない
- 実行結果(
復元完了: ... -> ...、行数の変化テーブル、prerestore_path)をそのままユーザーに提示する - 実行結果の提示後、サーバー再起動について改めてユーザーの明示承認を取る。上記1.の一括承認は再起動を含まないため、ここで新たにyes/noを得るまで再起動を実行しない。承認が得られたら、restart skillでClaudeが再起動する。復元の後はプラグインの更新を省き、再起動だけを行う。
restart_server.pyやkill・起動コマンドは直接打たない。 - MCP再接続後、経緯を
add_logsで追記する(実行結果)
Bを選んだ場合は、対象範囲の特定と手動SQL操作の手順を個別に提示し、実行前に再度承認を取る。サーバー停止を伴う場合は、停止前にAの2.と同様に現状を add_logs で記録する。
Cを選んだ場合は、誤検知と判断した理由を add_logs に記録してスキップする。
5. 再検証
- 復元後、主要データが戻っているかを確認する(
get_activities/search等、またはuv run --directory "${CLAUDE_PLUGIN_ROOT}" python "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.py" listで最新スナップショットの行数と突き合わせ) - 異常が解消していない場合、Step2に戻り別の復元候補(一つ古い世代等)を提案する
- 解消しない場合は「これ以上の自動復旧は困難」と報告し、ユーザー判断に委ねる(無限に世代を遡り続けない。現存する全世代を試して尽きたら停止する)
Edge Cases
| ケース | 期待挙動 |
|---|---|
| スナップショットが1件もない | 警告のみ提示し、復元不能である旨を伝える。「先に進む」以外の選択肢がないことを明示 |
復元に使えるスナップショットが全て quick_check 失敗(破損) | 破損している旨を明示し、直近の非破損世代 or 「復元不能」を報告する |
復元実行が失敗(RestoreBlockedError) | エラーメッセージをそのまま提示し、原因(サーバー稼働中 / 整合性検証失敗 / schema非互換)に応じた対処を提案。無断で --force / --yes を付けて再実行しない |
| 誤検知(直近の正当な大量retract等が原因と判明) | Cを選択してskipし、判断理由をlogに記録する |
| SessionStart警告以外でDB異常に気づいた場合(会話中に件数の少なさに気づく等) | 同じフローに入ってよい(TRIGGERの2つ目のケース)。Step1で「hook警告なし・自己認識起点」である旨を明記する |
| 復元後も異常が解消しない | Step5の通り別世代を試すか、解消不能として報告する |
注意
- 復元前の自動バックアップ(
prerestore退避)はrestore_snapshotが内部で行うため、このスキルが別途手動バックアップを取る必要はない - MCPサーバーの停止・再起動はユーザー影響が大きい操作。実行前に必ず明示的な承認を取る(一般的な「任せるよ」は承認とみなさない)
--force/--yesフラグは安全装置を無効化するものであり、スキル側が自発的に付与しない
decision-record
セッション中に成立した「合意」と、結論が出ないまま残った「未決論点」を add_decisions で記録する。判断基準・品質基準をここに集約しているため、add_decisions を呼ぶ前に本スキルの判定を必ず通す。
適用範囲
このスキルは初回 load 時に発動するが、判断基準は本セッション内のすべての後続ターンに適用される。以降のターンで下記の合意条件・未決条件に該当する出来事が起きたら、明示的に skill を再発動せずとも add_decisions を呼ぶこと。
対象
add_decisions(決定事項・未決論点の記録)
add_logs(経緯)/ add_material(成果物)は本スキルの案内対象外。両者は recording skill が担当する。
合意判定基準
以下のいずれかに該当する場合のみ、合意成立の decision として記録する。
- ユーザーが「OK」「それでいこう」「その方針で」「了解」「いいね」等で明示的に承認した
- AI の提案に対してユーザーの明示的な同意があった
- 「〜で決定」「〜に決めた」等、決定を宣言する表現があった
ユーザー合意のないものを decision として記録しない。片方(AI)だけが結論だと思っている内容や、まだ検討中の案は次項の未決論点として扱う。
未決論点の記録: [議論中]
結論が出ていない論点も、合意なしに記録してよい(決定の記録ではなく、議論の状態の記録だから)。
- 対象: 議論に出たが結論が出ていない論点、複数案が並んだまま収束していない検討事項
- 書き方:
decision本文の先頭に[議論中]プレフィックスを付ける。reason には検討中の選択肢と、どこまで詰まったかを書く - 発動タイミング: その論点のまま話題が移る、またはセッションが終わりに近づいたタイミング
- 待っているアクティビティの紐付け: その論点が決まるのを待って止まっているアクティビティがあれば、
add_relation("decision", <議論中のdecisionのid>, [{"type": "activity", "ids": [<アクティビティid>]}])で紐付ける(add_decisionsにrelated引数は無い)。以後、[議論中]の decision に紐づいたアクティビティは「その決着を待っている」と読む(結論の decision から問いへsupersedesを張って決着させる)
作業・話題が途中で終わった状態そのものの追跡は主にアクティビティ側の関心事であり、セッション終了時の一括記録(sync-memory)が [未完] を含めた整理を扱う。本スキルが扱うのは議論の論点であり、そこには [議論中] を使う。
呼び出し時の品質基準
- title: 付与を強く推奨する。check-in・timeline・search 等の一覧表示で decision 本文の代わりに見出しとして使われ、可読性が大きく上がる。文字数上限は
add_decisionsのdocstringに従う。tagsにlayer:directionを含める場合は title が必須になる(省略・空文字はエラー) - topic_id: 必須。適切な topic が無ければ、まず
add_topicで作成してから紐づける - tags:
domain:を必ず付け、内容を表す素タグも追加する。省略した場合は topic のタグを継承するが、内容が topic より具体的なら明示的に追加する - reason: 「なぜそう決めたか」を書く。
decision(結論)とreason(理由)を混ぜずに分離する - PRの表記: PRに言及するときは
owner/repo#123のようにリポジトリ名を付ける。番号だけでは、複数リポジトリを扱う記録から読み手がどのPRか解決できない
precedent定型節(任意)
reason の末尾には、任意で 却下案: / 適用条件: / 適用外: / 検証: / 隣接確認: の5種の定型節を書ける。書くと add_decisions のレスポンスに precedent として構造化されて返る(読み出し面 get_decisions / get_by_ids にも反映される)。
書式の正本は docs/precedent-format.md である(パーサ実装 src/services/precedent_pure.py と一致させる運用)。配布先のCWDではdocs/配下のパスが解決しないため、本スキル同梱の references/precedent-format.md に同一内容を保持している(内容の正誤に食い違いがあれば整合性テストで検知する)。定型節を書く前に references/precedent-format.md の2章(書式)を参照すること。
呼び出し時に外してはならない運用ルールのみ以下に挙げる:
- 節はすべて任意。「該当なし」を埋めるための空項目・ダミー項目は書かない(却下案が無い裁定に却下案節は不要)
- 実装状態(実装済み/未実装)は本文に書かない。状態は検証行の有無で読み手が判定する
呼び出し後の確認手順: 定型節を書いたら、レスポンスの precedent(rejected_alternatives 件数・scope bool・verification_anchors・adjacent_check)を見て、書いたつもりの節が反映されているか確認する。反映されていない、または precedent_warnings が付いている場合は書式ゆれの可能性がある。よくある原因: 行頭に無い、コロンが無い、箇条書きの - が無い、references/precedent-format.md 4章の近似見出し(却下例/棄却案/不採用案/適用範囲/対象外/検証済み/rejected/scope/近接確認/隣接チェック/周辺確認)を正規の見出しと誤って使った、等。precedent_warnings は soft validation であり、warning があっても decision 自体は作成済みで拒否はされない。warning は次回以降の書式修正の参考にする。
隣接確認:節(intent:design タグ推奨)
tags に intent:design を含む decision では 隣接確認: 節の記入を推奨する。書式は却下案と同じ「見出し行のみ + - 軸名: 内容 の箇条書き」で、対象は以下の2軸:
- 実行時: 誰が起動・デプロイする主体か
- 関連既決との整合: 既存の decision と矛盾・前提依存はないか
節が無くても記録は拒否されない(soft validation)が、precedent_warnings に intent:design decision missing '隣接確認:' section という警告が付く。intent:design を含まない decision には適用されない。
決定記録の直後にgoalの条件を満たす場合
add_decisions で記録した内容が、手元のgoalブロックの未終端の条件を満たすなら、続けて update_goal を呼ぶ。changes に {"op": "set", "id": <条件id>, "state": "satisfied", "note": "..."} を積み、同じ changes に {"op": "edit", "id": <条件id>, "bound": {"type": "decision", "id": <この決定のid>}} を並べて束縛する。
update_goal の応答の goal.label が judge_ready(全条件が終端し判定待ち)になったら、そのまま持ち越さずその場で判定する。goal.open_questions に未決があれば畳むか1ターン聞き、そのうえで goal.terminal の充足が1件以上あれば judge_goal(goal_id, verdict="achieved", note=...)、0件なら judge_goal(goal_id, verdict="failed", note=理由) を呼ぶ。人間の判断は待たず、判定したことの報告もしない。
この判定の分岐(open_questionsの扱いからjudge_goalの呼び分けまで)はcheck-inの「goalフィールドの扱い」節を正本とする。判定条件が変わる場合はそちらを確認する。
[議論中] の論点を結論の decision で決着させる場合は書き方が違う。決着する論点自体が条件の束縛先なら、結論の decision から問いの decision へ add_relation(relation_type="supersedes") で置き換えの関係を張る(既存の運用)だけでよく、update_goal は呼ばない(したがって上記の判定待ちの確認も発生しない)。この置き換えが張られた時点で、束縛した条件は次の読み出しから済と読まれる。決着前に条件を satisfied に書き換えると、束縛先がまだ済でないため崩れとして扱われる。
矛盾・重複への対処
add_decisions のレスポンストップレベルには related_decisions(呼び出し全体で同 topic 内の類似 decision 上位3件)が付く。既存 decision と矛盾する、または同一内容の重複だと気づいたら、その場で report_signal(kind="contradiction") を呼んで報告する。retract や supersede の判断そのものは本スキルの対象外。
tags に layer:direction を含めた場合はレスポンスに existing_direction_decisions(同 domain の有効な方向性 decision 全件)と direction_note も付く。既存の方向性判断と食い違う場合は、そのまま並存させるかの判断が必要になる。
recording との境界
recording: セッション中の「経緯」(add_logs)と「成果物」(add_material)を担当。合意が不要な記録decision-record(本スキル): 「合意」と「未決論点」(add_decisions)を担当。合意の有無を判定してから記録する
同じ出来事から log と decision の両方が生まれることがある(例: 3案比較の末に1案採択した場合、比較の経緯は recording が log として残し、採択という結論は本スキルが decision として残す)。両方に該当する場合はどちらもスキップしない。
sync-memory との関係
sync-memory はセッション終了前に transcript 全体を解析し、decision を含む記録漏れを一括で拾う安全網である。本スキルがセッション中に適切なタイミングで発動していれば、sync-memory 側の decision 記録ステップで新たに見つかる内容は少なくなるはずだが、本スキルは「セッション中の見逃し低減」が役割であり、完全網羅を保証するものではない。判断に迷ったら記録する側に倒す。
sync-memory のステップ2(未記録区間の記録)には、本スキルと同内容の要約(決定事項の判定基準・[議論中] の記録基準)が意図的にインラインで残っている。sync-memory は本スキルの発動を前提とせず単体で完結する必要があるためであり(docs/recording-taxonomy.md が採る「各 skill 本文は自己完結」の方針と同じ)、重複自体は許容する。ただし判定基準の記述が食い違った場合は、本スキル(decision-record)の「合意判定基準」「未決論点の記録: [議論中]」節を正本とする。
digest
指定期間(デフォルト直近7日間)に動きのあったアクティビティ・決定事項・成果物をdomainごとに俯瞰するダイジェストを生成する。ユーザーに期間内の動きを伝えることがゴール。読み取り専用skillであり、記録・更新は一切行わない。
「最近何やったっけ」「今週のまとめ」「ここ数日の動きを見せて」「先週から何が決まった?」など、期間ベースの振り返り・俯瞰の依頼で使う。
手順
1. 期間の決定
引数や会話中の期間表現があれば最優先で使う。
- 「今週」→ 今週月曜日 〜 今日
- 「ここ3日」「直近3日」→ 3日前 〜 今日
- 「先週から」→ 先週月曜日 〜 今日
- 「先月から」→ 先月1日 〜 今日
期間表現が無ければ、デフォルトの上限を直近7日間(today - 7日 〜 today)とした上で、文脈量に応じて短縮するか判定する。
get_activities(status="active", since=today-7日, limit=1)とget_activities(status="completed", since=today-7日, limit=1)のtotal_countを合算し、直近7日間で動いたアクティビティ数を確認する- 合算値が15件を超える場合は直近3日間に短縮する。超えない場合は7日間のまま使う(=「7日」と「文脈量に応じた短縮後の期間」のうち短い方を採用する)
- 実際に採用した期間(7日間 or 3日間)とその理由(短縮した場合は「直近7日間はN件と多いため直近3日間に絞った」)を出力冒頭に明記する
以降のsinceはISO日付文字列(YYYY-MM-DD)として扱う。
2. データ取得
get_activitiesとget_timelineのみを使う。record系ツール(add_*/update_*/retract等)は呼ばない。
get_activities(status="active", since={期間開始日}, limit=50)で期間内に更新された進行中・保留中のアクティビティを取得する。返り値のtotal_countが取得件数を超えていたらlimitを引き上げて再取得し、期間内の対象を取りこぼさないようにする(get_activitiesにoffset/カーソル等のページネーション手段は無く、取れる手段はlimit引き上げのみ)get_activities(status="completed", since={期間開始日}, limit=50)で期間内に更新のあった(updated_at基準)完了アクティビティを取得する。1と同様にtotal_countと突き合わせてlimitを引き上げて再取得する- 1・2で取得した各アクティビティの
id_raw(get_activitiesは整数idをid_rawとして返す。返り値にidキー自体は含まれない)を使い、get_timeline(activity_id={id_raw}, entity_types=["decision","log","material"], order="desc")を呼び、紐づくdecision/log/materialを取得する- アクティビティ数が多い期間(active+completed合計で20件超)では、この呼び出しがアクティビティ数に比例して増え応答が遅くなる。その場合は
updated_at降順で直近20件のみget_timelineを呼び出し、超過分はタイトルのみで一覧化して「他N件は詳細省略」と明記する(応答性を優先し全件深掘りはしない) get_timelineに期間指定引数は無い。デフォルトlimit=50・最大100。order="desc"(新しい順)で取得し、created_atが期間開始日より古いitemが現れた時点で以降は全て期間外なので打ち切ってよい- 取得件数がlimitに達してもまだ期間開始日まで遡れていない場合は、最後のitemの
created_atをbeforeカーソルに指定して追加ページを取得する(silent truncation防止)。ただしbeforeはcreated_atへの厳密な<比較のため、ページ境界と同一created_at(同秒)の未取得itemがあった場合はそのitemを取りこぼす可能性がある。本skillは概観目的の読み取り専用skillであり、この境界ケースでの完全性までは保証しない activity_id指定時は関連する全topicのエンティティを集約して返すため、そのアクティビティに紐づく決定・ログ・成果物を漏れなく拾える
- アクティビティ数が多い期間(active+completed合計で20件超)では、この呼び出しがアクティビティ数に比例して増え応答が遅くなる。その場合は
アクティビティに紐づかない独立トピックの決定事項は本skillの収集対象外(アクティビティ起点の集約のため)。該当topicの深掘りを求められたらget_timeline(topic_id=...)へ誘導する。
3. グルーピング
- 各アクティビティの
tagsからdomain:タグを抽出し、domainごとにアクティビティをまとめる - domainタグが無いアクティビティは「未分類」として最後にまとめる
- 複数アクティビティが同一topicを共有していると同一decision/log/materialが複数回取得されることがある。出力前に
id_raw(無ければtitle)で重複排除する - decisionは以下の順で分類する:
replaced_byが設定されている(=supersede済み)decisionは「決まったこと」から除外するか、「上書き済み」と明記して提示する。期間内の方針転換で古くなった決定を最新のように見せないtitleが[議論中]で始まるものは「継続中の論点」に分類する([未完]はactivity側のプレフィックスでありdecisionには付与されないため判定対象にしない)- 上記以外は「決まったこと」に分類する
- 各domain内では、アクティビティごとに収集したdecision/log/materialを種別(decision/log/material)で整理する
4. 出力
以下の構成でユーザーに提示する。該当がないセクションは丸ごと省略する。
digest: {期間の説明}({開始日} 〜 {終了日})
## {domain名}
### 動いたアクティビティ
- [完了] {activity.title}
- [進行中] {activity.title}
### 決まったこと
- {decision.title}({紐づくactivity名})
### 継続中の論点
- {[議論中]decision.title}
### 保存された成果物
- {material.title}
- domainが複数ある場合はdomainごとに上記ブロックを繰り返す
- 全体の量が多い場合はdomainごとの件数・要点のみ提示し、詳細はユーザーが指名したdomain/activityだけ展開する
注意
- 読み取り専用skill。
add_*/update_*/retract等の記録・更新系ツールは一切呼ばない - ユーザーへの提示はタイトルベースで行い、内部ID(
id_rawなど)は表示しない - 量が多い場合はdomainごとの要約を優先し、詳細はユーザーが指名したものだけ展開する
関連skillとの境界
- 単一アクティビティに絞った再開・進捗把握はcheck-inの担当。digestは複数アクティビティを期間横断で俯瞰する
- 完了アクティビティ1件を深掘りして教訓を抽出するのはpostmortemの担当。digestは俯瞰に留まり深掘りしない
- 記録から外部共有可能なドキュメントを生成するのはscribeの担当。digestはその場での提示のみで、ドキュメント成果物は作らない
env-config
利用者が調整する環境変数を見せ、変更を ~/.claude/settings.json の env に書く。一覧と既定値は手順書ではなくコードの台帳が正で、get_config が返す。
手順
get_config()を呼ぶ。env_varsが利用者の調整対象(kind: "user")の名前・既定値・説明・現在値を持つ。valueがnullなら未設定で、既定値で動いている- 一覧を「名前 / 現在の値(未設定なら既定値)/ 説明」の表で見せ、何を変えたいかを聞く。内部調整用・緊急スイッチ・セッションごとの変数(
get_config(env_kind="all")で見える)は勧めない。ユーザーが名指しした場合は、それが対象外の種類であることと、settings.jsonに書くと全セッションに効くことを伝えてから、書くかどうかを確認する - 変更内容(変数名・新しい値)をユーザーに見せ、確認を取る。確認なしで書かない
~/.claude/settings.jsonを読み、envに追記または更新する(他のキーと既存のenvは保つ)。ファイルが無ければ新規に作る。JSONとして壊さない- 最後に、反映には再起動が要ると案内する。MCPサーバーは常駐プロセスで、環境変数は起動時に読むため。restart skill でClaudeが再起動する
注意
- 設定の書き先は
settings.jsonのenvに限る。.mcp.jsonはプラグイン利用者が持たないため使わない - 値の型・単位は台帳の説明に従う。説明から読めないときは推測で書かずユーザーに聞く
forget
過去の記録(decision/log/material/habit/tag-notes/auto-memory/CLAUDE.md/rules/skill)が現状と矛盾・陳腐化していると判断したときに、撤回候補を提示し、ユーザー確認を経て撤回を実行するclaude自律発動スキル。撤回専用であり、新規の記憶・保存は remember skillの担当。
トリガー
発動する状況(状況認識、キーワード待ちにしない)
| # | 状況 | 発動タイミング |
|---|---|---|
| a | 新しいdecisionを記録した直後、過去のdecision/habit/tag-notesと矛盾すると気づいた | add_decisions直後 |
| b | ユーザー発話に方針転換のニュアンス(「やっぱり」「もう要らない」「あれはナシで」「今のは撤回」等)が読み取れる | 発話直後 |
| c | 作業・棚卸し中に古いhabits/rules/tag-notesと現状のズレに気づいた | 気づいた時点 |
| d | 議論クローズ(/af前後)で整理すべき撤回対象が見えた | クローズ操作の前後 |
発動しない状況
- 新規の記憶・保存依頼(remember skillの担当)
- 議論中でまだ結論が出ていない論点(撤回ではなく
[議論中]decision、decision-recordskillの担当) - ユーザーが直前に「forgetはいい」等、発動を明示的に拒否した直後
- ユーザーがClaudeの今の振る舞いを直したが、保存済みの記録に矛盾・陳腐化が無い場合(remember skillの担当)
- 同一タグで方針変更が繰り返されている、または構造的な再発が疑われる場合(単発の新事実による前提消失ではなく、再発原因の分析が要る。audit skillの担当)
起動時確認フロー
自律発動時、いきなり実行せず、まず検知内容を提示してユーザー承認を取る:
[forget] 過去の記録と矛盾・陳腐化している可能性を検知:
- 発端: (a〜dのどれで発動したか + 観察内容を1-2行)
- 撤回候補: (件数 + 種別の概要)
確認していい?
- A: 確認へ進む
- B: 今はいい
B選択時は何も実行せず終了する。
手順
1. 撤回候補の特定
- 発端となったトリガー(a〜d)を内部記録する。複数該当があれば§ 複数トリガー同時発動時の優先順位 に従いすべて記録する
- 撤回候補を1件または複数件、直近履歴・
search・文脈から抽出する - 各候補について「なぜ撤回候補と判断したか」の根拠を一言で言語化する(ステップ3の確認文で使う)
2. 保存先判定
候補ごとに保存先を判定し、実行方式を決める。実行方式は保存先によってretractツール・update_habit(active=False)・update_tag全文置換・物理削除のいずれかになる。判定表は § 保存先別の撤回方式 を参照。
対象がskillの場合は、実行前に § skill撤回時の依存検出 を行う。
3. ユーザー確認
撤回候補をユーザーに提示する。1件でも複数件でも、必ず個別にYes/No選択できる形で提示する(一括承認をデフォルトにしない)。
提示フォーマット:
撤回候補 (N件、発端: 検知順a→b→c→dで表示、複数該当は隠さず併記):
1. [対象] 撤回候補の要約
根拠: なぜ撤回候補と判断したか
方式: retract / update_habit / update_tag / 物理削除
→ Yes / No?
2. ...
ユーザーが1件ずつ回答する。ユーザー自身が能動的に「全部Yesで」と回答した場合はそのまま受け取ってよいが、エージェント側から一括承認を促す文言(「まとめて承認しますか?」等)は使わない。
4. 承認分実行
承認された候補のみ実行する。却下された候補は何もしない。
- CALM decision/log/material →
retract実行 - habit →
update_habit(habit_id, active=False)で無効化(retractはhabitを受け付けない) - tag-notes →
retractツール非対応のため、update_tagで対象箇所を除いた全文を書き込む方式で代替する - auto-memory / CLAUDE.md / rules ファイル → 物理削除
- skill → § skill撤回時の依存検出 で問題ないことを確認したうえで物理削除
- rules・habits・CLAUDE.mdの規則を撤回したら、規則名で
get_feedback_entries(query=<規則名>)を引く。bodyかrefに、撤回した規則の名前かその規則へのポインタが明示されているエントリ(鏡像)だけを対象に絞り、消すか直す。対象かどうか迷うエントリは消さず、add_feedback_noteでnoteを足すだけにとどめる。これはエントリの変更なので、ユーザーの確認は要らない。実行後に報告する
5. 実行結果をlogとして記録
撤回実行した内容を recording skill経由で add_logs に記録する。発端(a〜d)・撤回対象・却下された候補(あれば)を含める。
保存先別の撤回方式
| 保存先 | 撤回方式 | 備考 |
|---|---|---|
| CALM decision/log/material | retract | 論理削除 |
| habit | update_habit(habit_id, active=False) | retractはhabitを受け付けない(ENTITY_TABLE_MAPにhabitは存在しない) |
| tag-notes | update_tagで対象箇所を除いた全文を書き込む | tag-notesにretract概念はない(全文置換方式) |
| auto-memory(MEMORY.md / feedback_*.md等) | 物理削除 | ファイル削除 + MEMORY.mdの参照行削除をセットで行う |
| CLAUDE.md | 物理削除(行編集) | 周辺コンテキストを保全し、対象行のみ削除 |
| ~/.claude/rules/ | 物理削除 | ファイル削除。git管理下ならgit rm。cc-memory-habits.mdはhabitsの自動投影ファイルで対象外(habitの撤回はhabit行の方式を使う) |
| skill | 物理削除(重い確認 + 依存検出必須) | 実行前に § skill撤回時の依存検出 |
skill撤回時の依存検出
skillの撤回はgrepベースの簡易検出で十分とする(AST解析は過剰)。
- 対象skill名で他skillのSKILL.md本文・
hooks/hooks.jsonをgrep検索し、参照されていないか確認する - 参照が見つかった場合、依存箇所をユーザーに提示し、撤回を続けるか確認する(依存があっても最終判断はユーザー)
- 参照が見つからなければそのまま物理削除に進む
複数トリガー同時発動時の優先順位
複数トリガー(a〜d)が同時に該当する場合、検知した順(a→b→c→d固定)を表示順とする。該当するトリガーは隠さずすべて併記する(1つに絞らない)。
注意
- 撤回専用スキル。新規の記憶・保存はremember skillの担当
- ユーザー確認を経ない撤回実行は行わない(自律発動=全自動ではない。規則撤回に伴う鏡像エントリの掃除は除く)
- 判断に迷う場合は撤回しない側に倒す(false-positiveによる重要記録消失の方が実害が大きい)
initial-setup
インストール直後に1回行う。ゴールは「CALMが動く状態で、ユーザーが最初の一歩を踏み出せる」こと。
Step 1: 前提条件の確認
1つずつ確かめ、結果をまとめて報告する。満たしていないものがあれば直し方を添える。
- uv:
uv --versionが通ること。通らなければ https://docs.astral.sh/uv/ を案内する - MCPサーバーとembeddingサーバー:
uv run --no-sync --directory "${CLAUDE_PLUGIN_ROOT}" python "${CLAUDE_PLUGIN_ROOT}/scripts/restart_server.py" --statusを実行し、mcp_server.runningとembedding_server.runningを見る- embeddingサーバーは初回のencodeで起動する(モデル約290MBのダウンロードで時間がかかる)。
running: falseだけなら故障と扱わず、初回の検索後に再確認するよう伝える mcp_server.running: falseなら、/mcpからの再接続、直らなければ restart を案内する
- embeddingサーバーは初回のencodeで起動する(モデル約290MBのダウンロードで時間がかかる)。
- Pythonのsqlite拡張: サーバーは起動時にsqlite-vecの読み込みを検査し、失敗すると起動しない。
mcp_server.running: trueならこの検査は通過している。起動しない場合の直し方はdocs/troubleshooting.mdにある(Homebrew Python 3.12を使う)
Step 2: ペルソナのヒアリング
auto-memoryに既存のユーザーペルソナ(userタイプ)があれば読み、十分ならこのStepを飛ばす。
無い・薄い場合は、会話で聞く。「あなたの職種は?」のような項目埋め型の質問はしない。「普段どんなことにClaude Codeを使ってる? CALMで何をしたい?」のようにオープンに聞き、返答から職種・専門性・CALMで解決したいことをこちらで構造化する。案を一言で見せて、違えば直してもらう。
確認できたペルソナはauto-memoryのユーザーペルソナ(userタイプ)として記録する。project-setupはこの記録を読んで経路を選ぶ。
Step 3: 使い方の案内
ペルソナに合わせて、次の3つだけを短く案内する。詳細は man に任せる。
- 基本サイクル: 作業を始めたら
/calm:activity-start、再開は/calm:check-in、終わる前に/calm:sync-memory - 新しいプロジェクトを始めるときは
/calm:setup - 困ったら
/calm:man
範囲外
プロジェクトの知識フレーム作成は project-setup、環境変数の調整は env-config の担当。ユーザーが続けて望んだときだけ渡す。
man
以下の情報を元に、ユーザーの質問に合わせてCALMの使い方を説明してください。 全部を一度に説明する必要はありません。ユーザーが知りたいことに焦点を当ててください。 ユーザーが漠然と「使い方教えて」と言った場合は、基本サイクルから始めてください。
なお、Claude自身が状況判断のためにこのファイルを参照する場合は、基本サイクル・主要スキル・その他のスキル・記録の構造・goal機構、および「長く使っていくあなたに」内の環境変数表とスナップショット復元手順を情報源として使ってください。「熟練度別アドバイス」はユーザーへの語りかけ文体で書かれた説明用の文章であり、自分の行動判断の根拠にはせず、ユーザーに説明する際の材料としてのみ参照してください。
Claude自身は、次の瞬間にユーザー発話を待たず本ファイルを参照してよい。
- CALMの記録モデル(トピック/decision/log/activity/material/tag-notes/habits/goal)の使い分け、環境変数の既定値、スナップショット復元手順など、本ファイルにしかない情報を確認せず記憶だけで断定しようとしている
- ユーザーがCALMの機能・挙動を前提に話しているのに、自分がその機能を把握できていないと気づいた
次の場合は参照しない。
- どのskillを呼ぶべきか判断がつかないだけの場合(各skillのdescriptionはskill一覧で渡されている。ただし一覧の文字数予算を超えると、説明文が落ちて名前だけになることがある)
- 同一セッション内で既に参照済みの内容を再確認するためだけの場合
- 単一ツールの引数仕様など、そのツール自身のdocstringで足りる疑問
manは索引・説明用のskillであり、該当する【必須】skillが担う判定・手順(保存先の判定はremember、決定事項の記録はdecision-record等)を代替しない。
基本サイクル
CALMは「着手 → 記録 → 完了 → 同期」のライフサイクルで文脈を維持する。
- 作業に着手するとき:
/activity-start(/as)でアクティビティを作成する。既存の作業を再開するときは/check-inで選ぶ - 作業中: AIがトピック・決定事項・ログを記録する(ユーザーが意識する必要はない)
- 作業が完了したとき:
/activity-finish(/af)でアクティビティを完了にする - セッション終了前:
/sync-memoryを打つ → AIがセッション全体を振り返って記録を補完する。自動実行はされないため、必ず手動で打つ - 次のセッション開始時: AIが過去の記録を取得して文脈を把握する
ユーザーがやることは基本的に3つ: 作業を始めたら /activity-start、再開するなら /check-in、セッションを終える前に /sync-memory を打つ。
重要: /sync-memory の習慣化
/sync-memory はセッション終了前に手動で打つ必要がある(自動では実行されない)。
習慣化することを推奨する。記録が蓄積されれば、目に見えてAIの作業効率が上がることを実感できるはず。
主要スキル
/setup — セットアップ・設定変更の入口
- やりたいことを判断して、中のスキルに振り分ける。ユーザーが打つのはこのスキルだけ
- インストール直後: 前提条件(uv・sqlite拡張・embeddingサーバー)の確認、ペルソナのヒアリング、使い方の案内(initial-setup)
- 新しいプロジェクト・取り組みを始めるとき: 下記のproject-setup
- 環境変数による設定変更: 一覧を見せ、確認を取って
settings.jsonに書く(env-config)
project-setup(/setupの振り分け先)— 新しいプロジェクト・取り組みを始めるとき(一度だけの前準備)
- 新しいプロジェクト・取り組み(新しいdomain)の知識フレーム(プロジェクト識別子・主要な関心事・既に決まっている方針・直近やること・参照ポインタ)を対話的にセットアップする
- コード開発が目的なら、自動的に
coding-project-setup(リポジトリのREADME・docs等の走査を伴う)へ引き継がれる - 一度作れば、以降は基本サイクルで運用していく
- タイミング: 新しいプロジェクト・取り組みでCALMを使い始める最初の一度
/activity-start(/as)— 新しい作業を始めるとき
- 新規アクティビティを作成し、そのまま着手状態にする
- 「このissueの調査をアクティビティにして」のように、自分が管理したい粒度を指示できる
- タイミング: 新しい作業・議論・設計を始めるとき
/activity-finish(/af)— 作業が完了したとき、または中断するとき
- 現在のアクティビティをcompleted状態にする
- 完了ではなく、「一旦ここまで」「今日はここで止める」のように後で戻る前提で離れるときは、再開メモを添えて寝かせる(pending・snoozed・shelvedのいずれか)
- タイミング: 一つの作業のまとまりが終わったとき、または完了させず一旦離れるとき
/check-in — 作業再開時に打つ
- スキルを起動すると、AIが記録しているアクティビティの一覧が表示されるので、再開したいものを選ぶだけ
- 選択すると、関連する決定事項やこれまでの経緯を一括で取得してくれる
- もし期待していたアクティビティが一覧にない場合は、それはAIが自動生成に失敗しているということなので、AIに明示的に作成を依頼してみるとよい
- タイミング: 前回の続きの作業を再開するとき
/sync-memory — セッション終了前に打つ
- セッション中の議論・決定事項・ログをAIが自動で整理・記録する
- AIが記録し忘れた内容も、セッション全体のtranscriptを見て補完する
- タイミング: セッションを終える前。長いセッションでは途中で打ってもOK。自動実行はされないため必ず手動で打つ
- 2回目以降に打っても、前回の記録と重複して記録されることはないので安心して使える
その他のスキル
/postmortem— 完了したアクティビティを振り返り、うまくいったこと・いかなかったことを整理して、教訓をtag-notesやhabitsに永続化する。大きめの作業が終わったあとに/scribe— CALMに蓄積された記録(決定事項・ログ・資材など)からドキュメントを生成する。ADR、議事録、設計ドキュメントなどを書き起こしたいときに/tag-cleanup— タグの共起分析を実行して、似たタグの統合や不要タグの整理を提案してくれる。記録が増えてきたら不定期に/remember— 「覚えて」「保存して」と言ったときに、保存先(tag-notes/habits/auto-memory等)をAIが判定して振り分けてくれる/rule-placement— メタask裁定で発効した一般化ルールを、rules/habits/tag-notes/pin/判例decision/skill/ツールdocstring/server instructionsのどこへ配信するかを評価軸に基づいて判定する。/rememberの判定木で迷ったときや、1つの裁定に性質の異なる複数ルールが混ざっているときにも使う/audit— 過去の決定事項との矛盾や方針のブレを疑ったときに、経緯を掘り下げて正しい記録場所に整理し直す/recompose-context— アクティビティやトピックに散らばった関連情報を整理・統合し、次回のcheck-inを軽くする。整理範囲のアクティビティのgoal・親への結びつけも整える。「情報整理して」「まとめて」でも発動。--all(全体モード)ではアクティビティ(active/shelved/snoozed)全域を棚卸しし、実態確認のうえでcompleted化・shelved化・description訂正・重複統合・裁定待ちのいずれかに処遇する。「アクティビティ棚卸しして」で発動/db-recovery— SessionStart hookがDBデータ異常減少を検知したときに、スナップショット所在確認から復元実行・再検証までを自律的に進める。DB件数の異常な少なさに自分で気づいたときも対象/decision-record— ユーザーとの合意が成立したとき、または論点が未決のまま話題が移ったときに、決定事項の記録をガイドする/digest— 直近の記録を期間横断で俯瞰するダイジェストを生成する。「最近何やったっけ」「今週のまとめ」など期間ベースの振り返りに/overview— 今動いているもの・最近終わったもの・人間の裁定待ち・残りの内訳を一望表示する。「今何が進んでる」「全体状況見せて」などで発動/forget— 過去の記録が現状と矛盾・陳腐化していると判断したときに、撤回候補を提示してユーザー確認後に撤回する/recording— セッション中に発生した経緯(log)や成果物(material)を、判断基準に沿って記録する/ask-compose—add_askを呼ぶ前に、question/contextをテンプレートに沿って構成する。「これ聞いといて」「離席するから後で確認して」のように非同期の判断委譲を指示したときにも発動する/ask-distill—add_askのsimilar_asksを見て、同型の問いが繰り返され裁定が一貫していると気づいたときに、判例をまとめてメタask(kind="meta")を起票する/memory-export//memory-import— CALMの記録(トピック・決定事項・ログ・資材・アクティビティ)を他のCALMインスタンスとやり取りする。exportは書き出し、importは受け取ったバンドルの取り込み。知識を別環境・別の相手と共有したいときに/calm:restart— プラグインを更新し、calmのローカルMCPサーバーを強制再起動する(embeddingサーバーも先に停止され、新しいサーバーの起動直後に自動で立ち上がる)。コード変更や設定変更を反映させたいときに、Claudeが自分でrestart skillを呼んで実行する。ユーザーが打ってもよい/ask-watch— Ask storeをMonitorツールでイベント駆動監視し、同型の問いが繰り返されていないか確認する。「ask storeを監視して」「asksを見張って」等で発動/board— Claude同士の非同期のやり取り(質問・周知・意見募集・事前の声かけ)を、掲示板トピックへの投稿としてガイドする。相手が今生きていてすぐ返事が欲しいときはSendMessageで直接話しかける(このスキルの対象外)/peer-nudge— セッション台帳の宛先候補へSendMessageで直接話しかける前に、担当範囲の確認手順・書き方・配慮・返事が来ないときの扱いをガイドする。相手が今生きていない、または往復が1回で済まない意見募集はboardの担当/orch— 仕事を複数の子に分けてbgに振り、まとめ役として追う・引き継ぐ・終わらせる手順をガイドする。「orchとして進めて」「orchの状況見せて」「○○のorch終えて」などで発動
よくあるパターン
設計議論 → 実装の流れ
- 新機能の議論を始める → AIがトピックを作成
- 議論の中で方針が決まる → AIが決定事項(decision)を記録
- 設計が固まったら
/activity-startで作業アクティビティを作成 - 作業が完了したら
/activity-finishでアクティビティを完了にする /sync-memoryでセッション終了- 次のセッションで
/check-in、もしくは「〇〇の作業の続きをしていこう」→ 前回の決定事項を把握して実装開始
途中で中断した作業の再開
/check-inでアクティビティを選択- AIが関連のコンテキストを取得してくる
- 前回どこまでやったか把握して続きから再開
記録の構造
- トピック: 1つの関心事・問題・機能(話題が変わったら新しく作る)
- 決定事項(decision): 双方が合意した結論。「何を・なぜ」を記録
- ログ(log): 議論の経緯・生情報。決定に至るプロセスを保存
- アクティビティ: ある程度の活動の塊。デフォルトで議論・設計・作業の3つのフェーズを用意している
- リレーション: トピック・アクティビティ間の関連。check-inで2親等まで自動取得され、
get_mapでさらに探索できる - 資材(material): 長い生情報のオフロード先。独立エンティティとしてタグ付きで保存され、リレーションでトピック・アクティビティと関連付けられる
- タグノート: タグに紐づく常備情報。関連作業時にAIへ自動注入される
- 振る舞い(habits): 全セッション共通で従ってほしいルール。alwaysタイプは全文が
~/.claude/rules配下の自動生成ファイルに投影され、毎セッション開始時にシステムプロンプトへ自動的に読み込まれる。intelligentlyタイプは同じファイルに重要度順のタイトル一覧(マニフェスト、既定30件まで。CALM_PROJECTION_MANIFEST_MAX_ITEMSで変更可)だけが載り、超過分は本文を切断せず「他N件 → get_habits で確認」の1行に縮退する。本文が必要になればget_habitsをhabit_id指定で呼んで取得する。「materialの書き方」「コミット前の確認事項」など、常に従ってほしいルールを登録できる。AIに「覚えといて」と言えばOK
goal機構
goal機構は、アクティビティの終了条件を構造化し、いつ・誰が終わりを判定するかを明示するための仕組み。
何を保存し何を導出するか
- 保存するのは、goal本体(handle・statementと判定記録)、条件(真偽の付く1文・担い手・状態・束縛)、activityとの紐づけ(不要印を含む)の3種類だけ
- check_inやgoalツールの応答に載るgoalブロック(label・進捗・次の一手など)は保存しない。読み出しのたびに条件の状態から都度計算して返す導出値
4つのツール
set_goal: activityにgoalを新規作成して紐づける、既存の未判定goalに紐づける、不要印を付ける、紐づけ・不要印を外す、のいずれかupdate_goal: 条件の追加・状態変更(open/satisfied/waived)・担い手や束縛の変更・statementの修正。判定済みgoalを未判定に戻す差し戻し(reopen_reason)もこのツールjudge_goal: goalを閉じる唯一の手段。achieved(達成)かfailed(未達のまま終了)を記録し、紐づく未完了activityを同じ書き込みでcompletedにするget_goal: 読み取り専用。充足済みを含む全条件を返す(check_inのgoalブロックは要約と直近3件までしか返さない)
運用の勘所がどの瞬間に効くか
- 起票(activity-start): 終了条件を書く/不要印を付ける/何も書かない、の3択にする。雛形で埋めない。条件は真偽の付く1文で書き、Claudeが推した条件も追認を待たずそのまま書く。候補が複数で定まらない、または終わりがあるはずだが何なのか推せないときだけユーザーに聞き、定まれば書く
- 記録の直後(recording・decision-record): 条件を満たしたら、その場でupdate_goalに書く。根拠のdecisionなどがあれば、同じ呼び出しで束縛も張る。それで判定待ちになったら、そのまま判定に続く
- 待ち(ask-compose・activity-finishの中断): 会話や記録から満たされたと分かるなら確認せずsatisfiedに書く。分からない人間の判断待ちだけ、その場で聞けるなら聞いてdecisionにする。離席中・セッション跨ぎならaskにして、条件をそのaskに束縛する
- 判定(recording・decision-record・check-in・activity-finish・recompose-contextの全体モード): 全条件が終端になった判定待ちの状態を見たら、そのセッションがその場でjudge_goalを呼ぶ。判定したことの報告はしない。未決(openなask・[議論中]のdecision)があれば、判定の前に畳むか1ターン聞く
- 整理のついで(recompose-context): 整理範囲に出てきた未完了のアクティビティのうち、goalが未定義のものに記録から推せる終了条件を書く(推せなければ書かない。不要印は触らない)。振ったまとめ役が推せるなら、確認なしに親のgoalへ子を束縛先にした条件を足す。推定では条件を満たさず、判定もしない
- 事後の記録(sync-memory): transcriptから推せる終了条件は確認なしで書く。候補が複数で定まらない、または推せないときは書かない(事後の一括処理でユーザーに聞けないため未定義のまま残す)。外部の完了はghなど実際の手段で確かめられればsatisfiedに書き、確かめた結果で終端すればjudge_goalも呼ぶ。確かめられない推測はsatisfiedにも判定にも使わない
終了条件を書かない選択
不要印(set_goalの不要印)と未定義(何も書かない)は、どちらも正当な状態。常駐の活動や同じセッションで閉じる小作業には不要印、終わり方を考える判断材料がまだ無い作業や、聞いても定まらなかった作業は未定義のまま進めてよい。書くことは強制されず、check_inの次の一手が促すだけにとどまる。
差し戻しと環境変数
- 判定済みgoalを差し戻すと、signal_eventsに
goal_rollbackの行が自動で残る(手でreport_signalを呼ぶものではない。kindの詳細はreferences/signals.md) CALM_GOAL_RECHECK_HOURS(既定6時間): 担い手がhuman/externalのopen条件を「要確認」とみなすまでの時間
Ask store
Ask storeとは
Ask storeは、だいたいこういうデータフローを提供する仕組み。
作業中のAIがあなたに聞きたいことがあるけど、すぐに答える必要はない——そういうときにAIはその問いをAsk storeに登録する。次にどのセッションを開いても、起動した瞬間にその問いが自然と目に入る。答えると、元の作業をしていたセッションにその判断が伝わり、AIはそれを踏まえて作業を続ける。
つまり「今すぐ答えなくていい判断」を、あなたの好きなタイミングで拾えるようにする仕組み。
Ask storeの読み書き(add_ask・answer_ask・triage_ask・withdraw_ask)と完了通知ファイルの書き込みは、いずれもrelayと無関係に動作する。relay未接続時はrelay経由のクロスセッション通知が静かに省略されるだけで、ask自体の作成・回答・トリアージの成否には影響しない。
基本の使い方
- 判断待ちが溜まっていないか気になったら「asks見せて」とAIに聞くか、
/ask-answerで一覧して1件ずつ答えられる - 回答するときは、そのまま会話であなたの判断を伝えればAIが記録してくれる
- 回答しただけではその問いが元のactivityをブロックしている状態は解除されない。解除されるのは
triage_ask(promote/dismiss)またはwithdraw_askが実行されたときのみで、AIの自走裁定や次回のcheck-in等で拾われるまで待つ形になる
どのくらいの粒度で聞かれたいかはあなたが決める
「これくらいなら聞かなくていい」「これは必ず聞いてほしい」の線引きは人によって違う。自分なりの運用ルールをAIに伝えておくと、Askの粒度がその通りになっていく。
別の手段でも答えられる
calmのMCPツールを介さなくても、relayが提供するHTTP APIを直接叩けば、スマホやWebhookなど別の手段から回答を投げ込める。
熟練度別アドバイス
初めて使うあなたに
CALMは、セッション間で文脈を保持するためのツール。 セッションが終われば会話は消えるが、CALMに記録された情報は次のセッションに引き継がれる。
やることは基本的に3つ: 作業を始めたら /activity-start、前回の続きなら /check-in、そして セッション終了前に /sync-memory を打つ(自動実行はされないので手動で)。
これだけで、AIがセッション中の議論・決定事項・進捗をまとめて記録する。 次のセッションでは、AIが自動的に過去の記録を取得して文脈を把握した状態で会話を始められる。
/sync-memoryを毎セッション終了前に打つ。これが一番重要- 記録が貯まるほどAIの初手精度が上がることを実感できるはず
- 前回の続きの作業があるときは
/check-inでアクティビティを選ぶと、関連する決定事項や経緯を一括取得できる
使いこなしたいあなたに
CALMは情報を構造的に管理している。 主な記録単位は トピック(話題)、決定事項(合意)、ログ(経緯)、アクティビティ(行動の塊)、資材(生情報のオフロード先)の5つで、タグがそれらに横断的な特徴を付与する。
このうちトピック・決定事項・ログ・資材はAIが比較的うまく記録してくれる。 しかしアクティビティの切り方とタグの付け方は、AIだけでは精度に限界がある。 アクティビティとは行動の単位であり、「何をやるか」だけでなく「何をやらないか」を暗に定義する。 その境界を引くにはプロジェクト全体の文脈や優先度の判断が必要で、これはAIが持ち合わせていない知識に属する。
だから、ユーザーが能動的にAIに指示を出すことで記録の質が大きく変わる。
- アクティビティの範囲を指示する: 「このissueの調査をアクティビティにして」「設計と実装は別アクティビティに分けて」のように、自分が管理したい粒度で切るようAIに伝える。AIに任せると1セッション=1アクティビティになりがちだが、実際には1セッションで複数の話題を扱うことも、複数セッションで1つの作業を続けることもある
- タグを指示する: 「
domain:backendをつけて」「sprint-3タグで管理したい」のように、自分の整理軸をAIに伝える。domain:タグはアクティブコンテキスト(SessionStart hookの注入情報)のグルーピングに直結するので、複数プロジェクトを扱うなら早めに設計しておくと効く - 議論→設計→作業のフェーズを意識する: 急いで作業に入らず、議論と設計を丁寧にやるとAIの引き継ぎ品質が上がる。「まず議論フェーズで進めて」「設計が固まったら作業アクティビティを作って」のように、フェーズ遷移も明示するとAIが適切な
intent:タグ(discuss / design / implement)を付けてくれる - 繰り返し伝えていることをtag-notesに永続化する: 同じフィードバックを2回以上したら登録のサイン。「AIに毎回言い直している指示」があれば、それはtag-notesに書くべき情報。「このタグのnotesに追記して」と頼めばAIが
update_tagで書く
長く使っていくあなたに
CALMは使い続けるほど価値が出るツールだが、放っておいて勝手に良くなるわけではない。 AIが自力では知りえない情報をユーザーが教えてあげることで、記録の質と活用精度が根本的に変わる。
AIに教えるべき情報
時間を取って、以下のような情報をAIに伝えてみてほしい。一度伝えれば、tag-notesやhabitsとして永続化され、以降のセッションで自動的に参照される。
- 取り組んでいるプロジェクトの概要: 何を作っていて、なぜ作っているのか。AIはコードは読めるが、プロジェクトの目的やビジネス上の文脈は知らない
- プロジェクトとディレクトリの対応: 「このリポジトリは〇〇プロジェクトのバックエンド」「△△はこのmonorepo内のpackages/appにある」など。
domain:タグと紐づけておくと、check-in時の文脈取得が的確になる。ここに書ける情報は、リポジトリ内の相対パス・remoteのURLやowner/repo形式の識別子・サービス名など、書いた本人以外のマシン・セッションからも解決できる参照に限る(上の2例はどちらもこれに該当する)。tag-notesはcheck-in時に他セッションへ自動注入され、export機能で別インスタンスにも渡りうるため、自分のマシンでしか通じないローカル絶対パス(~/・/Users/...等)は書かない。そうした情報を残したい場合は/rememberの判定に委ねる - ユビキタス言語: プロジェクト固有の用語や略語。AIが勝手に別の言い回しで記録すると、後から検索で引っかからなくなる
データ保護(スナップショット)
CALMはセッション開始時(SessionStart hook)にDBの自動スナップショットを取得する。デフォルトでは12時間間隔で、最新5世代を保持する。スナップショットはDBと同階層の snapshots/ ディレクトリに保存される。
自動検知と警告:
セッション開始時にヘルスチェックが実行され、前回スナップショットと比較してテーブルの行数が100件以上減少している場合、AIに緊急警告が注入される。この場合はdb-recoveryスキルが検知確認から復元実行・再検証までを自律的に進める。以下の手順はその中で参照される詳細であり、db-recoveryを経由せず本節の手動手順だけを案内して終わらせてはならない。
スナップショットからの復元手順:
- 全てのClaude Codeセッションを閉じ、稼働中のMCPサーバーを停止する(DBへの書き込みを停止するため)。サーバーが稼働中(lock fileまたは
/healthエンドポイントの応答で検知)のままだと復元コマンド自体が中断する。停止はuv run --no-sync --directory "${CLAUDE_PLUGIN_ROOT}" python "${CLAUDE_PLUGIN_ROOT}/scripts/restart_server.py" --stopを実行する(復元コマンドが中断した場合も同じコマンドを案内する。停止済みを確認済みで続行したい場合のみrestoreに--forceを付ける) - ワンコマンドで最新のスナップショットから復元する:
特定の世代を指定したい場合はuv run --directory "${CLAUDE_PLUGIN_ROOT}" python "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.py" restore --latestuv run --directory "${CLAUDE_PLUGIN_ROOT}" python "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.py" restore <snapshot_db_path>を使う(パスは次項の一覧コマンドで確認する) - 復元前の現行DBは自動で退避される(
prerestoreスナップショット)ため、復元操作自体を誤っても退避先からやり直せる - Claude Codeを再起動する
スナップショット一覧の確認:
uv run --directory "${CLAUDE_PLUGIN_ROOT}" python "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.py" list
全kind横断のスナップショット一覧(kind・作成日時・サイズ・整合性チェック結果・パス)が表示される。復元先を選ぶ際の参考にできる。
サイレント劣化に気づく
CALMには「壊れてもエラーにならず、静かに機能が縮退する」種類の故障がいくつかある。データ消失(前項のスナップショット異常検知)とは別に、以下の3つは気づかないまま使い続けてしまいやすい。
embeddingサーバーの起動失敗
検索・check-in等でベクトル検索を使う際、embeddingサーバー(52836番ポート)が初回encode時に遅延起動する。起動に失敗しても例外は投げず、warningログのみを出して検索がキーワード一致(FTS5)のみに縮退したまま動き続ける。
- 気づき方:
uv run --no-sync --directory "${CLAUDE_PLUGIN_ROOT}" python "${CLAUDE_PLUGIN_ROOT}/scripts/restart_server.py" --statusのembedding_server.runningがfalseのまま。または後述のdegradedフラグが立ち続ける - 直し方: restart skillで再起動する(embeddingサーバーも一緒に入れ替わる)。
restart_server.pyやkill・起動コマンドを直接は打たない
検索応答のdegraded: true
searchツールの応答に含まれるdegradedは、その呼び出し時点でベクトル検索(embeddingサーバー)が利用不可だったことを示す。trueのときの結果はFTS5キーワード一致・タグ名一致のみに基づき、意味的には関連するが字面が異なる項目を取りこぼしている可能性がある。「類似する情報が見つからない」と判断する前に、AIはこのフラグを確認すべきである。
- 気づき方:
search応答のdegradedキーを見る(バリデーションエラー等でベクトル検索を試す前に結果が確定した場合はキー自体が無い) - 直し方: 少し時間を置いて再検索する、または上記のembeddingサーバー再起動を行う
hookが黙って失敗する
CALMの全hookはfail-open設計(1つのhookの失敗が他の操作を止めない)。この設計自体は意図的だが、失敗が既定では標準エラー出力にしか残らず、記録ナッジやSessionStart注入の一部セクションが黙って消えても「何も起きていない」ように見える。
- 気づき方: 以下のhookは、hook本体のコードが実行された後に起きた例外を
signal_eventsへkind: machine_errorとして記録する。get_signals()で確認できるほか、1件でもあればSessionStart注入の「未トリアージのシグナル」行にも現れる- SessionStart注入の各セクション(
sourceがhook:section:<セクション名>) - SessionStart hook本体(
sourceがhook:session_start) - Stop hook本体(
sourceがhook:stop)・記録ナッジ判定(sourceがhook:stop:logs_sparse) - PreToolUseの内部IDリークブロックhook(
sourceがhook:preblock) - UserPromptSubmit hook(
sourceがhook:user_prompt_submit) - PreToolUseのネストbg起動拒否hook(
sourceがhook:deny_nested_bg)
- SessionStart注入の各セクション(
- 直し方:
get_signals(kind="machine_error")でdetail・summaryを確認し、原因(依存モジュールの欠落・DBスキーマ不一致等)を調査する。記録は失敗の発生を示すだけで、自動修復はしない - 限界: この記録機構自体がDB層のimportに依存するため、venvの破損や依存パッケージの欠落でhookがimport時点で(
main()に到達する前に)落ちた場合は記録されず、標準エラー出力のみに残る。MessageDisplay等の表示専用hook・transcript sanitize系hook(別途citation_event_logへ失敗を記録済み)も現状この記録の対象外
カスタマイズできるもの
- tag-notes: タグに紐づく常備情報。そのタグに関連する作業が始まったときにAIへ自動注入される。「タグノート見せて」「このタグのnotes更新して」とAIに頼めば確認・更新できる
- 振る舞い(habits): 全セッション共通のルール。alwaysタイプは全文、intelligentlyタイプはタイトル一覧(マニフェスト)が
~/.claude/rules配下の自動生成ファイル経由でセッション開始時に読み込まれる(詳細は「記録の構造」参照)。AIに「覚えといて」と言えばOK intent:タグのtag-notes: 議論・設計・作業の各フェーズでAIにどう振る舞ってほしいかを定義できる。初期状態でdiscussとdesignが登録されている- 環境変数:
~/.claude/settings.jsonのenvフィールドで以下の値をオーバーライドできる。未設定ならデフォルト値で動作する。/setupから設定変更を選ぶと、一覧の表示と書き込みをAIが手伝う。変更後はClaudeがrestart skill(/calm:restart。プラグイン更新と再起動を行う)でMCPサーバーを再起動する。ユーザーが打ってもよい
| 環境変数名 | デフォルト | 説明 |
|---|---|---|
CALM_DB_PATH | ~/.claude/.claude-code-memory/discussion.db | データベースファイルのパス |
CALM_HEARTBEAT_TIMEOUT | 20 | ホットアクティビティ判定の閾値(分) |
CALM_TIER2_MAX_AGE_DAYS | 7 | SessionStart一覧の階層2にin_progressアクティビティを載せるupdated_at上限(日) |
CALM_PIN_SURFACE_DECAY_DAYS | 60 | pinnedアクティビティが階層2表示を維持できるupdated_at上限(日) |
CALM_TIER2_MAX_ITEMS | 5 | SessionStart一覧の『優先』に出す件数の上限。hookが読むため~/.claude/settings.jsonのenvで設定する。増やすときはCALM_INJECTION_BUDGET_ACTIVITIESも上げる(各セクションの予算の合計がCALM_TOTAL_INJECTION_BUDGET_CHARSを超えるとcomposeがValueErrorを出す。既定の合計は11100字で、総予算12000字との差は900字) |
CALM_RECENCY_DECAY_RATE | 0.0119 | 検索の時間減衰率 |
CALM_PRECEDENT_BUDGET_CHARS | 24000 | pull_precedentsが本文展開(decision+reason)に使う文字数予算 |
CALM_SYNC_DISABLE_RETROSPECTIVE | false | /sync-memoryのふりかえりセクションを非表示にする |
CALM_SNAPSHOT_INTERVAL | 12 | スナップショット取得間隔(時間) |
CALM_SNAPSHOT_MAX_COUNT | 5 | スナップショット最大保持数 |
CALM_SNAPSHOT_ANOMALY_THRESHOLD | 100 | 行数減少の異常検知閾値(件) |
CALM_SEARCH_HEALTH_WINDOW_DAYS | 7 | 検索縮退・クエリ拡張停止検知の集計対象ウィンドウ(日) |
CALM_SEARCH_HEALTH_MAX_SAMPLE | 100 | 同集計で見る最大件数(timestamp降順) |
CALM_SEARCH_HEALTH_MIN_SAMPLE | 20 | 同集計の判定に必要な最小サンプル数(未満なら常に健全扱い) |
CALM_SEARCH_HEALTH_DEGRADED_RATIO | 0.2 | 検索の縮退率がこの値以上なら異常とみなす閾値 |
CALM_SEARCH_HEALTH_QE_FIRE_FLOOR | 0.0 | クエリ拡張の発火率がこの値以下なら異常とみなす閾値 |
CALM_PROJECTION_MANIFEST_MAX_ITEMS | 30 | intelligently habitsマニフェストの掲載件数上限 |
CALM_GOAL_RECHECK_HOURS | 6 | goalの条件のうち担い手がhuman/externalのopen条件を「要確認」とみなすまでの時間(時間) |
CALM_PROJECT_ROOT | 自動解決(CLAUDE_PLUGIN_ROOT → git rev-parse --git-common-dir) | embedding_serverを起動するプロジェクトルート。優先順位は 明示設定 → プラグイン実行時はCLAUDE_PLUGIN_ROOTの値から自動設定 → embedding_server自身のgit rev-parse --git-common-dir解決 → いずれも失敗した場合はRuntimeError。加えて/calm:restart(強制再起動)実行時は、上記のいずれでも未設定であればrestart_service自身も同じgit-common-dir解決(gitリポジトリでなければ実行時のプロジェクトルート)で先回りして設定する。通常は自動解決されるため設定不要だが、いずれの自動解決にも失敗する環境(gitリポジトリ外かつCLAUDE_PLUGIN_ROOTも未設定)では明示設定が必要 |
環境変数は CALM_ 接頭辞に統一されている。旧名(CCM_ / CC_MEMORY_)も当面はフォールバックとして読まれるが、新名が設定されていればそちらが優先される。
現在の設定値はget_config()ツールで確認できる。
定期メンテナンス
記録が増えてくると、タグが散らかったり似たようなタグが乱立したりする。
不定期に /tag-cleanup を実行して、タグの共起分析と整理をしておくと、検索精度と分類の質を維持できる。
memory-export
起点(topic/activity)またはタグから到達可能な記録を選び、他のcalmインスタンスへ渡すバンドル(manifest.yaml + エンティティ別mdファイル)を書き出す。
手順
- instance_id確認:
get_configでinstance_idを確認する。nullなら未設定。DNSラベル風の命名規則(^[a-z][a-z0-9-]{2,31}$)を示してインスタンス名を1ターンで聞き、set_instance_identityを呼ぶ。一度設定すると原則変更不可(forceなしでは拒否される破壊的操作である旨を必ず伝える) - 起点の種類を確認: 「特定のトピック/アクティビティから辿る」か「特定のdomainタグ配下をまとめて渡す」かをユーザーの発話から判定する(不明なら1ターン確認)
- 前者: 起点テーマを
searchで探し、起点entity(topic/activity)をユーザーに確認する - 後者: 対象の
domain:タグを確認する。複数domainにまたがる知識を渡す場合は、tag_rootsを複数指定した1バンドルへ統合するのが正解であり、バンドルを分けない(本文中の参照は解決不能だとタイトル置換で非可逆に劣化するため、分割よりバンドル統合の方が受け手側の文脈が保たれる)
- 前者: 起点テーマを
collect_export_candidatesを呼ぶ。include_typesを明示指定してlogを除外する(["topic", "activity", "material", "decision"])。include_types未指定だと5型全部(logも含む)が返るため、logを既定outにするにはこの指定が必須- 起点方式:
roots(+max_depth、既定2) - タグ方式:
tag_roots(グラフ拡張はしない、深度ゼロ固定でシード集合に合流)
- 起点方式:
- 候補提示: 総候補件数に応じて提示ポリシーを切り替える(下表)
- 確定リストの復唱: 型別件数と主要タイトルを要約提示し、最終確認を取る
export_bundleを呼ぶ。selection引数に手順3の入力(roots/tag_roots/max_depth)をそのまま渡す(manifest.yamlに記録されるだけで、読み取り側の実装は無い)- 結果報告: 書き出しパス・型別件数・
auto_included(選択していないのに親topic自動同梱等で機械的に含まれたエンティティ。ユーザーが選んだ覚えのないものが同梱されている、と気づけるように必ず伝える)・unresolved_refs(受け手への申し送りになる旨。各要素にdomain_tagsが付くので「次にどのdomainのバンドルを追加で送ってもらうべきか」の判断材料になる旨を説明)・masked_literals件数 - export実行の経緯を
add_logsで記録する(recording skillの基準に従う)
候補提示ポリシー
| 状況 | 提示方法 |
|---|---|
| 候補が少数(目安: 総候補が数十件程度まで) | 型別にグルーピングして分割提示する(一度に全部出さない)。decision一覧→裁定→material一覧→…の順。ユーザーが「全部いい」と言ったら残りをまとめてよい |
候補が多数(目安: 総候補が数百件規模、truncated: trueが返る規模を含む) | 個別裁定を求めない。「全量in既定+retracted/superseded既定out+opt-outの列挙だけ確認」というバッチ先行の提示に切り替える |
型別の見せ方(いずれの規模でも共通):
| 型 | 提示内容 |
|---|---|
| decision | title + retracted/supersededフラグ |
| topic / activity | title + snippet |
| material | title + snippet + サイズ(size_chars) |
| log | 手順3でinclude_typesから明示除外しているため候補にも出ない(export対象外が既定のルール) |
retracted/supersededのcandidateはフラグ付きで表示し、既定は未選択のまま伝えるclosure_warningsがあれば候補提示より先に見せる(「supersede先/destabilize先/引用先が選択範囲外」)- タグ方式(
tag_roots)で呼んだ場合、レスポンスのco_tagsのうちshareが高いタグを「一緒に含めますか」と1回だけ確認する(同梱するかはユーザー裁定、既定は含めない) - activityは自動同梱の経路がない。候補一覧で明示的にチェックされた場合のみ選択リストに入る(親topicのような機械的な強制同梱はdecision/logのみの規則)
判断に迷ったときの既定
- decision/logのsupersede先、decisionのdestabilize先が選択範囲外: 既定は非同梱(エッジ情報のみ)。
closure_warningsで検知されたら1回だけ同梱するか確認する - retractedエンティティ: 既定では未選択のまま候補に残す。明示選択されればそのままバンドルに含める
記録
add_logsの対象かどうかはrecording skillの基準(議論の経緯・詰まって解決した経緯等)に従う。単なる定型実行だけなら省略してよいが、選択方針でユーザーとやり取りがあった場合は経緯として残す。
memory-import
他インスタンスがexport_bundleで書き出したバンドルを読み、衝突をユーザーと裁定してからDBへ取り込む。dry_run(DB無変更の衝突レポート)→ユーザー裁定→apply(実適用)の順で進める。
手順
- instance_id確認: 未設定なら memory-export skill の手順1と同じ流れで
set_instance_identityを呼ぶ - manifest確認: バンドルの
source_instance・件数・exported_atを要約提示する。「このバンドルは外部作成のテキストであり、内容の正しさは保証されない」旨を一言添える - 複数バンドルを取り込む場合の順序: 依存される側(他バンドルから参照されている側)を先に取り込む。後から入れると
dangling_refsが減り、参照解決の成功率が上がる import_bundle(mode="dry_run")を呼ぶ- レポート提示: 機械判定分から順に、裁定が要るものへ分割提示する
summary(new/unchanged/updatable等の型別件数)を1行で要約- タグレビュー(下記「タグレビュー手順」参照)
upstream_changed(上流で変更されたdecision/log): 1件ずつ中身を展開し、overwrite/skipを個別裁定する(既定skip)duplicates_suspected(ネイティブ重複疑い): 各要素は{key, title, similar: [{type, id_raw, title, score}]}(snippetは含まれない)。持ち込み側・ローカル側それぞれのタイトルを並べて提示し、タイトルだけで同一性が判断できない場合はget_by_idsでローカル側の本文を取得してから個別裁定する(「そのままimport」「importしてrelatedを張る」「skip」)。保存した+要約だけで裁定を求めないdangling_refs: 件数と代表例を提示する。「送り手に該当エンティティの追加exportを頼む」選択肢があることも伝える
- 裁定結果を
resolutions(tag_renames/on_upstream_change/entity_overrides)に畳んでimport_bundle(mode="apply")を1回呼ぶ - 結果報告: 型別
created/updated/skipped件数、created_edges/dropped_edges。取り込んだtopicと既存のローカルtopicとの関連付け(add_relation)を能動的に提案する - import実行の経緯を
add_logsで記録する(recording skillの基準に従う)
タグレビュー手順
tag_reportの各エントリ(create/merge/alias_hit/archived_hit)は「notes展開+同名異義一次判定」を一体で行う。判定はタグnotesではなく、双方の**使用実体サンプルtitle(最大5件)**を主証拠にする(notesを持つタグは全体の一部にすぎないため)。
1. review_required で振り分ける
create/merge/alias_hitの各エントリはreview_required(namespace がdomain、または incoming/local に notes がある場合に true)を持つ。これを見て:
review_required: false: 個別裁定を求めずバッチで一括承認する(件数のみ要約提示)review_required: true: 下記2の一次判定を1件ずつ会話内で行う
archived_hit(archived同名)にはreview_requiredフィールドが無い。既存タグがarchivedである時点で過去に何らかの理由で退役している=同名衝突の判断コストが高いため、件数によらず常に1件ずつ個別確認する(バッチ一括承認の対象外)。
2. AI一次判定(review_required=trueのみ)
型別に展開する内容:
| 区分 | 展開する内容 |
|---|---|
create(新規作成) | notes全文 + incoming.sample_titles |
merge(既存合流) | notes_diff(追加分の差分) + local.sample_titles + incoming.sample_titles |
alias_hit(エイリアス該当) | resolved_to(解決先canonicalタグ) + local.sample_titles + incoming.sample_titles |
archived_hit(archived同名) | archived_reason + incoming.sample_titles。新規タグとして作り直すか、archived状態のまま据え置くかを確認する |
local.sample_titlesとincoming.sample_titles(merge/alias_hitのみ、alias_hitは解決先canonicalタグの使用実体title)を見比べ、AIが3値のいずれかを一次判定する:
- 同一: 同じ対象を指している → そのままmerge(タグをリネームしない)
- 異義: 別の対象を指している → リネームを提案する(
tag_renamesに追加)。命名慣行は送り元instance_id接頭辞(例: 送り元がteam-aでdomain:apiが異義ならdomain:team-a-api) - 不確か: 判別できない → 次項の非対称ルールで倒す
3. 「不確か」時の非対称ルール
- domainタグ(
namespace == "domain"): ユーザーに個別確認する(疑わしきは聞く) - 素タグ(domain以外): 自動でmerge扱いにする(疑わしきは合流)。誤って合流させても
import_provenance経由で個別修復が可能なため非可逆ではない
4. ファイル出力は補助のみ
会話内展開が主経路。タグ件数が多く会話に収まらない場合のみ、レポートをファイルへ書き出して補助的に使ってよい(「保存した+要約」だけで裁定を求めない、という運用原則はここでも同じ)。
判断に迷ったときの既定
- 上流変更されたdecision/log: 既定skip(受け側で既にそのdecisionに依存した記録が育っている可能性があるため)
- ネイティブ重複疑い: 機械判定ではなく必ずユーザー裁定(embedding類似検索は支援情報にすぎない)
- 参照解決不能: applyが自動でタイトル置換(「「{title}」(未取り込みの外部記録)」)する。ここはユーザー裁定を挟まない機械規則
記録
add_logsの対象かどうかはrecording skillの基準に従う。タグ同名異義の裁定やupstream_changed対応でユーザーとやり取りがあった場合は経緯として残す。
orch
全体像
orchとは、orchタグの付いた未完了のアクティビティで、説明の先頭に「担い手」欄を持つもの。担い手欄に名前とsessionIdで書かれた窓口が、今のorchの担当(今の担い手)である。担い手欄が「空席」、または書かれた窓口が生きていない状態は異常ではない。子として振ったbgは動き続け、報告はログに溜まる。
一生のサイクルは次の順で回る。
- なる: 仕事を受けた窓口が、自分1体で抱えきれないと判断したら、orchになる(同じ範囲のorchが既にあれば、それに合流するか担い手に頼む)
- 振る: 子をbgに切り出し、束縛してから起動する
- 追う: 子とbgの状態を見る
- 一覧: すべてのorchの担い手・bg・子を一望する(朝はこれに加える形で使う)
- 空ける/代わる: 窓口を閉じるとき、次に触った窓口が引き継ぐとき
- 終える: 子が済んだ、またはユーザーの了承を得て閉じる
orchの担い手は、子になる作業をサブエージェントやWorkflowでも自分でせず、必ずbgに振る。orchが自分でやるのはまとめ役の仕事(振り分け・状態の確認・他セッションとの調整・ユーザーへの取り次ぎ)と、自分の判断のための協議(相談役との協議)だけである。
orchは束ねるだけでなく、担当範囲の成果に責任を負う。判断が要る場面では、ユーザーに聞く前に、相談役との協議と実データの収集(調査・実測はbgに振る)で自分で詰める。相談役とは、判断の材料と案を返すだけの相談専用のサブエージェント(その環境で呼べる設計・推論向けのロール。無ければ、判断の論点と材料を渡して案を求めるサブエージェント)を指す。協議は結論を出すための相談で、調査・実測・実装の作業は含まない。結論と責任はorchが持つ。ユーザーに上げるのはユーザーに上げるものの列挙に当たるものだけで、それ以外は在席でも自分で決め、決めた内容と根拠を報告する。
発動の範囲
「orchとして進める」「bgに振って」「orchの状況見せて」「○○のorch続けて」「○○のorch終えて」などのユーザー発話のほか、窓口のClaudeが自分1体で抱えきれないと判断した場面でも自発的に発動してよい。orchタグの付いたアクティビティにcheck-inしたとき(check-in skill経由か、check_inツールの直接呼び出しかを問わない)は、ユーザーの発話がただの「続きやる」「チェックイン」でも必ず発動し、代わる節から入る。
窓口が自分1体で抱えきれないと判断する目安は、判断の要る子の目標が2つ以上ある・長く待つ、に加えて、次のどれかに当たるとき。
- スコープが広くなりすぎた
- 複雑すぎて、やるべきことに自信が持てない
- 情報が足りなすぎる
- 文脈のコントロールが1体ではしんどい
bgに振らずその場で完結する単発の作業やレビューには発動しない。
なる
同じ範囲のorchがあるか確認する
一覧節の手順でsearchし、同じ範囲のorchが既にあるか確認する。
- 空席なら引き受ける(代わる節の手順)
- 担い手がいればその窓口に頼む(peer-nudge skill経由)
orchは無いが、同じ範囲を束ねる未完了のまとめ役(orchタグも担い手欄も無い「[統合]」など)があるとき、またはユーザーが既存のアクティビティを名指ししてorchにするよう頼んだときは、新しく起票せず、それをorchにする(既存のまとめ役をorchにする)。新しく起票すると、同じ範囲に親が2本並ぶ。
無ければ起票する
- activity-startを経由せず、
add_activityを直接呼ぶ(check_in=True)。intentはintent:discuss - タグに
orchを含める。domainや内容を表す素タグも付ける - 説明の先頭に状態節の雛形を置く(状態節とgoalの雛形節を参照)。担い手欄には自分を書く(
claude agents --jsonでpidが$CLAUDE_PIDの行のnameとsessionIdを使う) - 起票と同じ手番で、goalを付ける。形は起点で選ぶ(状態節とgoalの雛形節)
- 最初に振る子が既に分かっているなら、起票のあとすぐに振るへ進み、子を束縛してから開始の宣言を返す
担い手空席の常設orchとして起票する
recompose-context skillで、束ね役の親の提案にユーザーが了承したときの起票。bgに振る話ではなく、同じテーマの子を束ねるために立てる。
- 無ければ起票すると同じに
add_activityで起票する。担い手欄は「空席」とする。この時点ではgoalを書かない - 了承された子を束縛する。根拠はユーザーの了承で、条件の書き方だけ既存のまとめ役をorchにするの手順4の末尾の段落に合わせる(子にgoalが無ければ後付けする)
- 束縛した条件を持つ常設のgoalを書く(状態節とgoalの雛形節。束縛してから書く)
- 開始の宣言は返さず、立てたorchと結んだ子の題を一言で伝える。担い手が要るときは「○○のorch続けて」で引き受けられる
既存のまとめ役をorchにする
get_by_idsで今のタグと説明を読み、get_goalでgoalのlabelを読む。labelがclosed(判定済み)なら、そのアクティビティはorchにせず無ければ起票するへ進むupdate_activityを1回だけ呼び、説明とタグを同時に書き換える。分けて書くと「タグはあるが担い手欄が無い」途中の状態ができ、一覧の付け替えがタグを外してしまう- 説明: 先頭に状態節を置く(状態節とgoalの雛形節)。担い手欄には自分を書く(名前とsessionIdの取り方は無ければ起票すると同じ)。bg表には、報告先がこのアクティビティで生きているbgがあればその行を書き、無ければ「(無し)」とする。約束・預かり・反映待ちは「(無し)」から始める。元の説明は、役割と範囲として状態節の下に残す
- 元の説明のうち「orchではない」など、orchでないことを前提にした記述は消し、代わりに経緯へ「{日付}にorchにした(それまではorchでないまとめ役)」の1行を残す。雛形の「書かないもの」に当たる記述(他のorchの担当セッション名、運用規約の写し)も消す
- タグ: 読んだタグを全部含め、
orchを足し、intentをintent:discussに替える。update_activityのtagsは全置換なので、読んだタグを落とさない
- 同じ手番で、goalを形に合わせる。形は起点で選ぶ(領域を束ねてきたまとめ役なら常設になるのが普通)
undefined: 雛形どおりset_goalで作るnot_needed(常駐の不要印):set_goal(..., replace=True)で雛形のgoalに置き換える。不要印のまま残さないactive: goalは作り直さない。常設にするなら、update_goalのop=addで錠の条件(担い手human、「ユーザーがこのorchを終えることを了承した」)を足す。期限付きならそのままにする
- 範囲の中で、まだ束縛していない既存のアクティビティを、下の基準で子にする
- 開始の宣言を返す。新しく作らず「[統合] ○○」をorchにしたことを含める
既にある未完了のアクティビティを子にするのは、記録から、このorch(またはorchにする前のまとめ役)の仕事として切り出されたと推せるものに限る(recompose-context skillの「親への結びつけ」と同じ基準・同じ条件の書き方)。別のorchの子として束縛済みのもの(各orchのget_goalの条件のboundに出るもの)は子にしない。別の窓口が作業中のものも、基準に合えば束縛してよい。束縛しても作業する窓口は変わらない。子にgoalが無ければ、束縛するときに後付けする(書き方はrecompose-context skillの「goalが未定義」と同じ)。goalが無いままだと、束縛した条件「子のgoalがachievedで閉じた」を満たせない。
開始の宣言
起票(または既存のまとめ役をorchにする手順)が済んだら、次を含む一言をユーザーに返す。
- orchとして回すこと
- 形(期限付き/常設)
- 戻ってくるもの(PRのマージ、判断が要るときのask、止められた操作の許可)
見本:「これは子が3本に分かれて判断も要るので、bgに振って私がorchとして回すね。『[統合] ○○』を作った。形は期限付きで、子が全部済んだら閉じる(ずっと持つ常設にしたければ言って)。あなたに戻ってくるのは、PRのマージと、判断が要るときのask。止められた操作の許可が要るときは、まとめて頼む」
振る
数える
振る前に、claude agents --jsonで全セッションの生きたbg(kind=backgroundかつpidあり)を数える。ユーザーとの取り決めの上限を超えるなら、超えない範囲まで待つ。
束縛して起動する
子1本につき、次の3段を同じ手番で続けて行う。
add_activityをcheck_in=Falseで呼び、子を作る(orchタグは付けない。このタグはorchアクティビティ自体にだけ付ける)- 子に
set_goalでgoalを作る - orchのgoalに
update_goal(op=add)で、子のアクティビティへ束縛した条件を足す
続けて依頼文ラッパー(${CLAUDE_PLUGIN_ROOT}/scripts/bg_dispatch.py。必須引数は--activity-id・--activity-title・--worktree・--parent-goal-handle・--parent-condition-id)で起動する。親goalの指定を必須にする(orchの子は依頼文ラッパーで親goalを指定して振る)。起動後、waitingForを1回見て、起動の入口で止まっていないか確かめる。起動できたら状態節のbg表に1行足す。
期限付きのorchにも、最初の子と範囲の違う子を後から足してよい。2本目のbgのために2本目のorchを作らない。
起動後のbgに、起動時の範囲の外の仕事を送らない。範囲外の残件は新しい子として振る。
起動形
信頼済みのディレクトリで、作業ツリーの中から起動する。止まったらwaitingForを見る。zshのクォート・特殊文字のエスケープに注意する。リポジトリ別の起動場所の具体は、環境ごとの私的な取り決めに従う。
依頼文の書き方
依頼文ラッパーが生成する依頼文に、次を含める。
- 報告先: 親のorchアクティビティ。bgは報告を常にそのアクティビティへ
add_logsで書く - 越えない線: 外向きの操作(他人のブランチ・外部サービスへの書き込み)、
~/.claude配下の変更、既決を見直すことになる判断、auto modeや権限に止められた操作は、進めずに報告先へ返す。止められたら迂回しない - 待たずに進む範囲: 上の線の内側の実装上の判断は、確認が要る場面でも待たずに最も妥当な方針で進め、判断をPR本文と報告に書く
- 人間宛てのaskを起票しない: 人の判断が要るときは報告先へ返す
- EnterWorktreeは使わない
- マイグレーション番号: 必要になったら、origin/mainとopen PRの番号の最大値+1を取り、報告先へ宣言する。返事は待たずに進む。兄弟のbgが同じ番号を取ることはありうるが、yoyoは番号が同じでもファイル名が違えば別のmigrationとして扱い、適用順は
-- depends:で決まるので、衝突しても壊れはしない。番号を直すのは後からマージするPR(後発側はマージ順で決める)で、マージする者(orch)がマージ前にorigin/mainと突き合わせ、重なっていれば次の空き番号に振り直させる - 兄弟との連携: 兄弟(同じ親goalに束縛された他の子)の担当に関わる事実(共有ファイル・マイグレーション番号・mainの破損・前提の変化)を見つけたら、報告先に加えて、その兄弟へもSendMessageで知らせる義務。兄弟の一覧は依頼文に埋め込まず、受けたbgが親goalのconditionsとget_sessionsから引く(orchは子を順に振るので、起動時点では後から振る兄弟が決まっていない)。送るのはこの周知だけで、作業の依頼・質問・進捗は送らせない
- 止める前の
sync-memory --minimal: 最後の報告の前に実行する - 禁止は狭く書き、方針でなく「説明と決定事項に従う」ことを書く。依頼文に
"ultracode"やWorkflowの実行指示を書かない(やってはいけないこと節)
追う
生死の規則は2本ある。
- bgの生死:
claude agents --jsonでkind=backgroundかつpidあり。stateは生死を表さない - 窓口(担い手)の生死:
claude agents --jsonで、担い手欄のsessionIdが一致しpidがある行がある(kindは問わない)。名前は判定に使わない。Remote Controlの窓口やbgは起動後に名前が自動で変わるため、名前の一致を求めると生きている担い手を死んでいると読んでしまう。そのような行が複数あれば(/resume後に並ぶことがある)startedAtが最も新しい行を担い手とする(/resumeすると同じsessionIdの行が増え、新しく開いた側が今使われている窓口になるため。両方にpidがあっても新しい側に送る) - 担い手への知らせの宛先: 上で選んだ行の今の
name。担い手欄に書かれた名前は人が読むための表示で、宛先には使わない
許可待ちはwaitingForがpermission promptのときと見分ける。attentionの「止まっている」は見に行く候補で、CI待ち・許可待ち・単純に止まった・まだ振っていない、を上の規則で見分ける。
goalのchildrenの「達成」は外した子(waived)を含む。内訳はget_goalの条件で読む。次の一手の規則11が束縛した子について「進める」と返したら、orchでは「振る、または振った子の様子を見る」と読む。
報告済みで次の指示を待っているbgは、要らなければsync-memory --minimalを済ませていることを確かめて止める。
一覧
search(keyword="orch", tags=["orch"], entity_type="activity")で引き、get_by_idsで状態と説明を読んで未完了だけを残す- 説明の先頭に担い手欄が無いものはorchとして扱わない。
orchはorchの目印専用のタグなので、その場で外し、内容に合う素タグに付け替える。CALMのorchの運用を話題にしているものはorchestration、別の意味(プロダクトの部品名など)なら、その意味が分かる別の語(例: プロダクト名を前に付けた語)にする。別の語は、先にsearch_tagsで近い既存のタグを探し、あればそれを使う。update_activityのtagsは全置換なので、今のタグを読んでから渡す。付け替えはユーザーに確かめず、他の窓口のアクティビティでも行い、付け替えたことを一覧に1行添える。orchにしたいまとめ役だったなら、既存のまとめ役をorchにするの手順で付け直す claude agents --jsonで、担い手欄のsessionIdが一致しpidがある行があるかを見る(生死の見方は追う節の窓口の生死の規則による)- 各orchの
get_goalのchildrenと状態節のbg表を添える
「各orchに○○して」と頼まれたら、この一覧の生きた担い手(その行の今のname)を宛先にし(担当確認・作業依頼はpeer-nudge skill経由)、空席のorchにはログを書く。
朝の一覧
「おはよう、どうなった?」のような呼びかけに対し、上の一覧に次を添える。
- マージできるPR(CI・bot指摘の状態、順序の制約つき)
- 止まっているbg(いつから)
- askの件数(
get_overviewのawaiting_humanから) - 空席のorchの後始末(担い手欄の更新後に溜まったログの件数、Claudeの条件が出揃ったorch、マージ済みで判定待ちの子)
- 期限付きで閉じたorch
- マージ後にユーザーがやること(状態節の反映待ちから作る)
空ける
ユーザーが窓口を閉じると言ったとき(「閉じるから」「終わるから残して」など)に行う。
- 状態節を最新にし、担い手欄を「空席」にする。後任は決めない
- 生きているbgは止めずに残してよい(bg側が最後の報告の前に
sync-memory --minimalを済ませている) - ユーザーに「このorchは空席にした。続けるときはどの窓口でも『○○のorch続けて』」と一言伝える
sync-memoryを実行する窓口が、このorchの担い手で、ユーザーが窓口を閉じると言っているときは、sync-memoryの前に先に「空ける」を行う。閉じないsync-memory(途中の記録)では空けない。
代わる
次にこのorchに触った窓口が行う。
check_inする- 担い手欄を自分に書き換える。
claude agents --jsonでpidが$CLAUDE_PIDの行のnameとsessionIdを書く。担い手欄は、以前の値にかかわらず無条件で今の自分の値に書き直す(/resumeではsessionIdが同じまま名前とpidだけが変わるので、sessionIdが一致していても書き直しを省かない) - 状態節の更新時刻以降のログ(空席中のbgの報告を含む)を読む
claude agents --jsonでbgの生死を見直し、報告済みで次の指示を待つbgのうち要らないものを止める
bgへ報告先の変更を伝える手順は要らない(bgは報告のたびに担い手欄を読んで宛先を引くため)。
orch同士の約束・待ちは、宛先を相手のorchアクティビティの題で書き、送る時点で相手の担い手を引く。相手が生きていれば(追う節の窓口の生死の規則)、担当確認や作業依頼はpeer-nudge skillを通して、その行の今のnameへSendMessageする。空席なら相手のアクティビティにログを書く。
終える
常設・期限付きの終わり方
- 常設: Claudeの条件(子の条件)が全部終端したら、担い手が1回だけ「このorchを終えてよいか」を聞く
- 在席ならその場で聞き、答えで錠をsatisfiedにするか、続ける範囲を子にする
- 不在・空席ならaskを起票し、
update_goalのop editで錠の条件のboundをaskにする。問い文に答え方を書く(「終えてよければ『終えてよい』。続けるなら追加の範囲を書く」) - 答えが「続ける」なら、同じ
update_goalの呼び出しで、op editで錠のboundをnullに戻し、op set(state=open、noteに日付)を送る。追加の範囲を子にして束縛する - 束縛先askが回答済みで規則10(束縛先は済んでいる)が出たら、
satisfiedにする前に回答の中身を読む。「続ける」ならsatisfiedにせず束縛を外す(orchタグのnotesにも同じ読み方がある) - ユーザーの「終わったってことだよね?」のような疑問の形の発話も終える確認の合図として受け取り、1ターンで「終えてよいか」を確かめる
- 期限付き: 子が全部済めば判定待ちになる。ユーザーの確認を経ずに閉じる前の始末へ進み、閉じたことを一言伝える
閉じる前の始末
- openの子ごとに行き先を決める。別のorchに渡すなら渡す先のgoalに束縛を足してから、こちらの条件を理由付きでwaivedにする。やめるなら理由付きでwaivedにし、子を閉じる
- 生きているbgは
sync-memory --minimalを指示してから止める - 預かりは別のorchの預かりに移すか、アクティビティかaskにする
- 反映待ちが残っていれば、朝の一覧の「あなたがやること」に出すか済んだことを確かめる
judge_goalで閉じる。ユーザーが終えてよいと明言したときは判定の主体を人間(judged_by="human")にする。閉じたことを、在席ならその場で、不在なら朝の一覧で一言伝える
子を閉じる最後の一手(マージを確かめて人間の条件を満たし、子のgoalを判定する)は、その子を束縛するorchの担い手が持つ。マージした窓口が担い手でなければ、担い手へ知らせる。担い手が空席なら、マージした窓口がその一手だけを済ませ、orchのログに書く(代わらない)。
作業ツリーは子の持ち物とし、子を閉じるときにその子を束縛するorchの担い手が消す。auto modeに止められたらまとめてユーザーに頼む。
activity-finishでこのアクティビティを閉じようとしたら、ここ(「終える」)へ進む。
隣のorchへの検査
orch自身が設計の決定事項をadd_decisionsで記録する前に、隣のorchへ1回だけ検査を頼む。自分の文脈では見えない既決との衝突・前提の抜けを、別の文脈から指摘してもらうため。
- 一覧節の手順で、担当範囲が近い別のorch(domainと素タグが重なるもの)を1つ選ぶ。生きているかは追う節の窓口の生死の規則で見る
- 生きていれば、決定事項の案とその根拠を添え、「既決との衝突や前提の抜けがないか見てほしい」とpeer-nudge skill経由でSendMessageする。検査は1回だけで、返事への再検査は頼まない
- 返事が来るまで、そのdecisionの記録は保留する。他の作業は続け、次の手番までに返らなければ、検査なしで記録し、記録の本文に「検査を頼んだが返答なし」と書く
- 返事の指摘を判断して、案を直すか、そのまま記録する。指摘を採らないときは理由を記録に書く
- 空席、または宛先に送れないときは、検査を省いて記録する
ユーザーとの合意で決まる決定事項や、実装上の判断には使わない。
ユーザーに上げるもの
次はユーザーに上げる。それ以外は、在席でもorchの中で相談役との協議と実データの収集で判断して進め、決めた内容と根拠を報告する。
- PRのマージ(1本ずつ名指し。マージの前にclaude botの指摘を確かめ、マイグレーションを足すPRはorigin/mainと番号を突き合わせて、重なっていれば振り直させる)
- auto modeに止められる外向きの操作
- 大きな手間や費用(取り決めたbgの本数の上限を超えることを含む)
- ユーザー設定の変更
- ブランチの削除
- 既決のreasonがユーザーの意図に基づくものの見直し
skill・docsだけのPRを自分でマージしてよいという私的な許可がある場合は、それに従う。許可が無いか止められたら、名指しでユーザーに頼む。
上の列挙に当たる判断待ちは、在席ならその場で聞いて決定事項にし、不在・夜間・空席ならaskにする。askは、待たせている人間の条件の束縛に張り(無ければ人間の条件を足して張る。子に束縛した条件には張らない)、待たせるアクティビティをblocksに入れる。orchの説明とログには、判断待ちの中身を書かない。
マージの承認はPRを名指しした形で頼む(見本:「PR AとPR Bをこの順でマージしてよい、と言ってくれれば続けてやる」)。ユーザー自身の文に両方のPR番号が入っていることを確かめる。短い返事で2本目が止められたら、そのPRを名指しして聞き直す。1本ごとにmainへの到達を確かめてから次へ進む。スタックPR(子のbaseが親のブランチ)なら、親をマージした後に子のbaseがmainに切り替わったことを確かめてから子をマージする。
askの回答をマージの承認として別セッションで使うことはしない。マージはorchの窓口で名指しの承認を得てから行う。askの回答後の実行は、そのaskが結びつくorchの担い手が持つ。結びつくorchが空席のときと、orchに結びつかないaskは、トリアージした窓口が実行まで持つ(代わらない)。実行できないなら、ログで手放さず、結びつくorchの預かりに書くか、新しいaskにする。
やってはいけないこと
- orchの担い手の窓口では、子になる作業をサブエージェントやWorkflowでも回さない。子はbgに振り、bgの中ではサブエージェントを使う(orch自身の判断のための相談役との協議は子の作業ではないので許す。許すのは相談だけで、調査・実測・実装はbgに振る)
- ユーザーに上げるものの列挙に当たらない判断を、協議と情報収集を経ずにユーザーへ投げない
- bgの中のWorkflowは、ユーザー本人がそのbgに
attachして自分の言葉で頼んだときだけ使う。依頼文に"ultracode"やWorkflowの実行指示を書かない - ユーザーが子をWorkflowで回したいと言ったときは、その場でどちらの道にするか聞く(子を起票して束縛し、条件のnoteに「orchの窓口で実行中(ユーザー指定)」と書いて自分で実行するか、bgを振ってそこへattachしてもらうか)
- EnterWorktreeは使わない
- マイグレーション番号は、報告先へ宣言してから取る(返事は待たない)
- 人間宛てのaskを、bgに起票させない
- CALM内部の運用裁定の範囲を超えて、既決を見直すことになる判断を自分だけで決めない
状態節とgoalの雛形
orchアクティビティの説明の先頭に、次の状態節を置く。上書きで保ち、書くのは記録に無いものだけである。書かないもの: 子の状況(goalにある)、PRの番号と状態(子のgoal・bgの報告・PR本体から引く)、ユーザーの判断待ち(askにする)、他のorchの担当セッション名、運用規約の写し。
## 状態
担い手: {名前}(sessionId {sessionId})/{更新時刻}
(または 担い手: 空席/{更新時刻})
bg表:
- {子の題} / {bgの短いid} / {作業ツリー} / {起動時刻}
約束:
- {相手のorchアクティビティの題}へ{内容}
預かり:
- {内容}(1件ずつ)
反映待ち:
- {内容}
goalは起点で常設か期限付きかを選ぶ。
- 常設: 束ねた子の条件と、担い手humanの錠「ユーザーがこのorchを終えることを了承した」を持つ
- 期限付き: 束ねた子の条件だけを持つ。子が全部済めば判定待ちになる
どちらの形も、最初に振る子を束縛してから書く(束縛条件が無いと空の条件になる)。期限付きでは、振ると分かっている子を振り出す前に全部束縛する。範囲の違う子を後から足してもよい。
overview
「今何が進んでいて、次に何をすべきか」をユーザーに一望で見せる読み取り専用skill。判定ロジック(何日以内なら動いている扱いか、in_progressの宣言と実態の乖離、トリアージ未了の扱い、domainタグのcanonical解決)はすべてget_overviewツール側に集約されており、本skillの手順は表示の整形だけを行う。
手順
get_overview()を1回だけ呼ぶ。ユーザーが期間や件数を指定していればdays/limitに渡す。他のツール(get_activities/get_asks等)は呼ばない。- 返ってきた4節を
working→recently_done→awaiting_human→backlogの固定順で見出しにして出す。順序を入れ替えたり節を統合したりしない。 working/recently_done/awaiting_humanはitemsを1行1件で列挙する。workingはis_liveが trueのものに印を付け、days_since_touchとopen_ask_count > 0を添える。awaiting_humanはdays_openとblocksのタイトルを添える。awaiting_human.triage_pending_items(回答済み未捌き)が1件以上あれば、itemsとは別枠でquestionを列挙する(triage_pending_countの件数表示だけで済ませない)。awaiting_human.goal_human_waiting(goalの人間条件待ち)が1件以上あれば、askとは別枠で条件文・activityのタイトル・days_openを列挙し、goal_human_stale(完了・棚上げしたactivityに残った閉じ忘れ)は「閉じ忘れ」として更に別枠で出す。awaiting_humanはitems・triage_pending_items・goal_human_waiting・goal_human_staleがすべて空のときだけ見出しごと省略し、他の節はitemsが空なら見出しごと省略する。backlogはtotal_count/stale_in_progress_count/by_status/by_domain/no_domain_countをそのまま提示する。個別のアクティビティは列挙しない。- いずれかの節(
goal_human_waiting・goal_human_staleを含む)でcount < total_countなら「上位N件のみ表示(全M件)」と明記する。記録系ツール(add_*/update_*/retract等)は一切呼ばない。
注意
- 読み取り専用skill。
add_*/update_*/retract等の記録・更新系ツールは一切呼ばない - ユーザーへの提示はタイトルベースで行い、内部ID(
id_rawなど)は表示しない - 「今週これだけ完了した」のように
recently_doneの件数を完了実績として語らない(updated_at近似のため、完了後の編集で再浮上しうる)
関連skillとの境界
- 期間を指定して複数アクティビティ・決定事項・成果物を横断的に振り返るのはdigestの担当。overviewは期間指定を持たず「今の状態」のスナップショットに徹する
- 単一アクティビティへの着手・再開はcheck-inの担当。overviewは個別アクティビティへの深掘りをしない
working/recently_done/awaiting_human/backlogの判定基準(鮮度窓・heartbeat・トリアージ扱い・domain canonical解決)はget_overviewツール(src/services/overview_service.py)が持つ。本skillに集計ロジックを書き足さない
peer-nudge
セッション台帳の宛先候補に、SendMessageで直接・同期的に話しかけるときの作法をまとめる。非同期のやり取り(質問・周知・意見募集・事前の声かけ)はboardスキルの担当であり、対象外。
発動契機
- ツール応答に「📮 [宛先候補]」が現れ、実際に話しかけようとしている場面(判定待ちのgoalに関連する他セッションが見つかった、掲示板トピックへの投稿で関連する他セッションが見つかった、など)
- ユーザーが同期の声かけ(「近くのセッションに聞いて」等)を明示的に指示した場面
対象外
- 相手が今生きていない、または往復が1回で済まない意見募集:
boardスキルの担当(議論トピックを立てる) - 単なる作業報告・進捗共有
担当範囲を確かめる
話しかける前に、相手の担当範囲をまずget_sessions(台帳)で確かめる。直接「担当は?」と聞くのは、範囲がかぶってそうなときだけにする。
担当が重なっていそうな場面で、get_sessionsを引かずに窓口セッションへ直接問い合わせ、相手を別のセッションと取り違えた実例がある。台帳の情報で先に確認できる場合が多く、直接聞くのは最後の手段にする。
何を書くか
用件を簡潔に。何を確認・依頼したいのか、対象のactivity/topicが分かる形で書く。
相手の作業を邪魔しない配慮
相手は別の作業に集中している可能性がある。緊急でなければ、boardスキルでの非同期のやり取りも検討する。話しかける場合も、即答を前提にしない書き方にする。
返事が来ないときの扱い
深追いしない。相手が別の作業に集中している、または一時的にアイドルなだけの可能性がある。急ぎなら人間に相談する。急がないなら、掲示板(boardスキル)への切り替えを検討する。
ポストモーテム
completedアクティビティの行動を時系列で振り返り、ユーザーと対話しながら教訓を抽出・永続化する。
関連skillとの境界
- 「この作業を振り返りたい」のような、完了した作業の振り返りの依頼で使う
- 完了操作そのもの(activity-finish)と記録の同期(sync-memory)では発動しない
1. 対象アクティビティの選択
- 引数で
activity_idが指定されていればそのまま使う - 指定されていなければ
get_activities(status="completed", limit=15)で一覧を表示し、ユーザーに選んでもらう - 一覧はタイトルのみで提示し、内部IDは表示しない
2. ポストモーテムアクティビティの作成
対象が決まったら:
- 新しいアクティビティを作成:
- タイトル:
[振り返り] {元アクティビティ名}のポストモーテム - タグ:
intent:discuss,振り返り, + 元アクティビティのdomain:タグを引き継ぐ related: 元アクティビティとリレーションを張る([{"type": "activity", "ids": [元アクティビティID]}])
- タイトル:
- check-in する
3. データ収集とステップ分解
対象アクティビティに関連するデータを収集する:
- check-in結果の
related_topicsからtopic_idを取得する。related_topicsが空の場合は、アクティビティのタグでsearchするか、ユーザーに関連トピックを確認する get_logs(entity_type="topic", entity_id=topic_id)でログを取得get_decisions(entity_type="topic", entity_id=topic_id)で決定事項を取得get_map(entity_type="activity", entity_id=...)で関連エンティティを探索し、追加の情報源がないか確認するsearch(entity_type="material")/get_materialで資材を確認
データ不足の判定
ログが2件以下、かつdecisionも1件以下の場合:
データが少なくて、ステップ分解が難しいかも。
ログ: {N}件 / decision: {N}件
このまま進める?(ユーザーが口頭で補足しながらやることもできる)
ユーザーが続行を選んだ場合は、ユーザーに「何をやったか」を聞きながら手動でステップを組み立てる。
ステップ一覧の作成
ログを時系列で読み、行動の切れ目でステップに分解する。以下のフォーマットで全ステップの一覧を先に提示する:
## ステップ一覧
1. {ステップ名} — {1行の概要}
2. {ステップ名} — {1行の概要}
3. ...
この分け方で進める?追加・統合・分割があれば言って。
ユーザーの確認を待ってから次に進む。
4. ステップごとのレビュー
エージェントは材料を並べる係に徹し、評価はユーザーに先に出してもらう。1ステップずつ、以下の構成で提示する:
### ステップ {N}: {ステップ名}
**何があったか**:
{ログから読み取れる事実を時系列で要約}
**補足コンテキスト**:
{検討した代替案、関連decision、当時の制約条件など。なければ省略}
ここ振り返ってみてどう?
- エージェントは事実と文脈を提示するが、よかった/悪かったの評価は書かない
- ユーザーが意見を述べ始めたら、エージェントも自分の見解を出してよい
- 「ここは別のやり方もあった?」「この判断の背景って何だった?」など、振り返りを深める問いかけを使う
ユーザーの発言は次ステップに進む前にログとして記録する。
5. 反省ポイントまとめ
全ステップのレビューが終わったら、反省ポイントを一覧で出す:
## 反省ポイントまとめ
### よかったこと
- ...
### 改善したいこと
- ...(各項目に「なぜ起きたか」の1行分析を添える)
この一覧を add_material でポストモーテムアクティビティに保存する。
6. 教訓の永続化
最後に、改善したいことの中から次に活かせる教訓をどう永続化するか議論する。
永続化の手段はケースバイケース。以下は選択肢の例:
- tag notes: 特定のintentやdomainに遭遇したときに自動注入されるルール
- decision: トピックに紐づく合意事項
- auto memory (feedback): Claude Codeのセッション横断で適用される行動ルール
- CLAUDE.md: プロジェクト全体に適用されるルール
- 新しいintentタグ: 行動パターンが根本的に異なる場合
エージェントは選択肢を提示するが、何をどこに落とすかはユーザーが決める。
永続化が完了したら、ポストモーテムアクティビティの description に結論を追記し、ステータスを completed にする。
注意事項
- 急がない。1ステップずつ丁寧に。ユーザーが「次」と言うまで進まない
- エージェントの評価を押し付けない。「ここは問題だった」ではなく「ここ気になったんだけど、どう思う?」
- ユーザーの発言はできるだけ原文に近い形でログに残す
- セッション跨ぎの可能性があるので、進捗はこまめにログ記録する
project-setup
新しいプロジェクト・取り組みの知識フレームをセットアップする。ゴールは「次のセッションがcheck_in・searchで文脈を取れる状態」。最初に相手(ユーザー)を知り、相手に合った充填経路を選ぶ。
発動しない場面
- 既にフレームが立っているdomainでの通常作業
- 保存先が未確定の「覚えて」系依頼(remember skillの担当。本skillは新規domainのフレーム新設に限る)
新規domainのフレーム一括作成は、本スキルを経由せずに直接行わない。
フレーム定義(最低限ここまで)
充填経路によらず共通のゴール。職種中立の語彙で定義する。
| # | 項目 | 落とし先 |
|---|---|---|
| F1 | プロジェクト識別子+一言説明 | domain:タグ新設 + notes |
| F2 | 主要な関心事 2〜4個 | 素タグ(固有概念にはdescription付与) |
| F3 | 既に決まっている方針 | decision(ユーザー裁定を経て記録) |
| F4 | 進行中・直近やること | activity |
| F5 | 参照すべき場所 | domain/素タグのnotesに参照ポインタ(他マシン・他セッションから解決できるものに限る) |
F5に書けるのは、URL・サービス名・共有ドライブやドキュメントツール上の場所など、書いた本人のマシン以外からも解決できるポインタに限る。マシンローカルの絶対パス(~/・/Users/...)やユーザーレベル設定配下(~/.claude/等)は書かない。CALMの記録はcheck_inで他セッションのtag notesとして注入され、export等でpeerを超えて人に渡りうるため。ローカル固有の場所しか出てこなかった場合はF5を空のままにし、その情報を残す必要があれば remember の判定木へ流す(セットアップ独自の仕分けをしない)。
本skillが設計上あらかじめ落とし先を固定している書き込み(フレームF1〜F5、およびStep 1のauto-memoryへのペルソナ記録)は、保存先が未確定の依頼を扱う remember の判定対象ではない。判定が要るのはフレームに収まらない知識のほうで、そちらは後述のとおりrememberの判定木へ流す。
タグは単独で新設できない。domain:タグ・素タグは、それらをtagsに載せたエンティティ書き込みで初めて実体化する。notes・descriptionの付与はその後段でしか行えない。
topicは中身が載るときだけ作る。中身のないtopicを儀式的に先に立てても検索・紐づけの足場にならない。本skillではセットアップの経緯ログとF3のdecisionが中身にあたるので、それらを載せる器としてこのセットアップを表すtopicを1件だけ作る。F3が空(decisionが1件も無い)でも経緯ログは残るのでtopicは作る。議論用のtopicを先回りで乱立させない(議論のtopicは議論が始まってから自然発生に任せる)。
Step 1: プロファイリング
- auto-memoryに既存のユーザーペルソナ(userタイプ)があれば読む。十分ならStep 2へ直行する
- 無い・薄い場合は内部推定する。材料: userレベルの設定(
~/.claude/CLAUDE.md・rules・導入済みskill/plugin)、作業ディレクトリとホームディレクトリの構成、ここまでの会話の文脈 - 推定するのは「職種・専門性」と「このセットアップの目的」。ユーザーに「あなたはエンジニアですか」と直接は聞かない(内部推定が原則。判定不能なときだけ、目的を普通の言葉で聞く)
- 推定・確認できたペルソナはauto-memoryのユーザーペルソナ(userタイプ)として記録する。既存ペルソナと矛盾したら上書きせずユーザーに確認する
- プロファイリングは取り込みではない: userレベル設定の内容をCALMの記録(decision/material/notes)へ転記しない
Step 2: 経路選択
- 判定を一言宣言してから進む(例:「コードプロジェクトのセットアップとして進めるね」)。黙って振り分けない。違っていればユーザーがここで訂正できる
- コードプロジェクト × 開発目的 → coding-project-setup sub-skillへ委譲する(以降の手順はそちら)
- 「開発目的」とは実装・保守などコードを書く/変更する作業が主目的であることを指す。コードプロジェクトでも目的がドキュメント整備・調査のみで実装を伴わない場合は開発目的に含めない。判断に迷ったらStep 3(職種中立経路)に倒す
- それ以外 → Step 3(職種中立経路)へ
経路の追加はこのStepの分岐に足す(現時点の分岐はcodingのみ。二分岐固定の設計ではない)。
Step 3: 職種中立経路(会話ヒアリング)
- フォーム型の質問リストを提示しない。「一言で何?」「N個挙げて」のような要約・圧縮・選別の作業をユーザーに課さない
- オープンな聞き方で始める(例:「このプロジェクトのこと教えて。何をやるやつ?」)。ユーザーの自由な発話を充填材料として扱い、F1〜F5への構造化はAIが行う(coding経路のmd走査と同じ位置づけ)
- 発話から充填案(domain名と一言説明の起草・タグ候補・decision候補)を構成して提示し、裁定を受ける
- 裁定の粒度を分ける: **タグセット(F1/F2)**はまとめて一括承認でよい。**decision候補(F3)**は1件ずつ中身を展開して個別裁定する
- domain名の案が固まったら、提示の前に
search_tags(query=<候補名>, namespace="domain", include_notes=True)で既存タグとの衝突を確認する。namespaceを絞らない・include_notesを省いた呼び出しでは判定材料(notes)が返らない。search_tagsはタグ名のLIKE一致とベクトル検索のハイブリッドなので意味的に近いだけの別名タグも返る。衝突判定は返却されたnameの完全一致で行い、上位ヒットの有無では判定しない。usage_countは判定に使わない(retract済みを含む付与回数で、余談1件でもすでに1以上になるため区別できない) - 完全一致するdomain:タグが無ければそのまま続行する。ある場合は以下で分ける。
archived(検索結果の各タグに付くbooleanで、退役済みかどうかを示す)がtrueのタグも完全一致として扱い同じ分岐に入る(archivedの値で扱いが変わるのは最後の枝だけ)get_activities(tags=["domain:<名前>"], status="active")が1件以上返る → F4が埋まっており稼働中のフレームが既設。本skillの対象外なので、見つかったアクティビティ名を挙げてそのアクティビティへのcheck-inを案内して終了する(check_inはactivity_idが必要なため、案内は具体的なアクティビティを名指しする)- 0件なら
status="snoozed"・"shelved"・"completed"でも個別に呼ぶ。statusの既定値"active"はpending+in_progressしか返さず、全ステータスを一括で返す値は存在しないため、この追加呼び出しを省くと寝かせてある・終了済みのフレームを見落とす。1件以上返る → 過去にフレームが立っている(寝かせてある / 終了済み)ので、見つかったアクティビティを挙げ、そこへ合流するか・同じdomainで立て直すか・別名で新設するかをユーザーに裁定させる - どのステータスでもアクティビティが無く、
notesが空でない → 取得した既存notesをユーザーに提示し、別名で新設するか既存domainへ合流するかを裁定させる(合流する場合、Step 4のnotes書き込みは新規作成ではなくマージになる) - アクティビティも
notesも無い場合、archivedがfalseならそのまま続行してフレームを埋める(過去の言及だけでタグが実体化した状態)。archivedがtrueなら退役済みでフレームが立っているとは扱わない。同名で立て直すか別名にするかをユーザーに確認してから進む(別名にするなら新しい名前でこの確認をやり直す)
- 埋まらなかった項目だけ、会話の流れに沿ってフォローアップで聞く(例: F4が空なら「じゃあ最初は何から手をつける?」、F5が空なら「資料とかドキュメントってどこに置いてる? 自分のPC以外からも見られる場所にある?」)
- 「わからない・まだ無い」は正当な回答。F1のみ必須、F2〜F5は空のまま進めてよい
- タグ作成規律はcoding経路と共通: 素タグは少なめ(2〜4個目安)、description(100字以内の一言定義)を付けるのはプロジェクト固有の意味・実体を指すタグのみ。一般語彙タグには付けない
- フレームに収まらない知識(規範・判断基準・手順・背景の生発話)は remember の判定木で置き場を判定する(セットアップ独自の仕分けをしない)
Step 4: 書き込みと報告
- 書き込みは2段構成。タグを実体化させるエンティティ書き込みが先、タグ属性(notes・description)の付与が後になる
- このセットアップを表すtopicを
add_topicで1件作る(title 35字以内、descriptionにセットアップの目的と範囲を書く)。tagsにはF1のdomain:タグとF2の素タグをすべて載せる。これがタグを実体化させる器を兼ねるので、素タグを載せ忘れると後段のdescription付与がNOT_FOUNDで落ちる - セットアップ実行の経緯を
add_logsで記録する(recording skillの基準に従う)。topic_idには1で作ったtopicを指定する - decision(decision-record skillの規律に従う。
topic_idは1で作ったtopic)→ activity(activity-start skillの規律に従う) - タグ属性を
update_tagで付ける: domain:タグのnotes、固有概念の素タグのdescription、F5の参照ポインタ(domain/素タグのnotesへ)。update_tagはnotesとdescriptionを同時指定できず、notesは全文置換なので、domain:タグのnotesは一言説明と参照ポインタをまとめた最終形を1回で書く。既存notesを持つdomain:タグへ書く場合は、Step 3のsearch_tags(include_notes=Trueで呼ぶ)で取得した既存notesを保持したままマージした全文を書く(全文置換なので、書かなかった内容は消える)
- このセットアップを表すtopicを
- 作成したフレームの一覧(タグ・decision件数・activity・ポインタ)を提示する
運用開始後の増分は対象外
会話中に未知のドメイン固有概念に遭遇したときのインタビューは、habit(未知概念インタビュー)が担う。本skillは初期一括のみ。
recompose-context
指定された入口(activity/topic/decisionどれでもOK)から関連する全情報(topics, decisions, logs, materials)を読み込み、統合material(anchor対応表付き)の生成・軽照合・リコンサイル・tag pin・tag-notes更新を行う。次のcheck-inだけで作業に必要な情報が全部揃っている状態を作ることがゴール。
anchorの新規作成・更新の対話手順は references/anchor-setup.md に従う。「anchor作って」「検証先決めたい」など、anchorだけを決めたい依頼でもこの手順だけを使う。
モード
- 局所モード(既定): 入口から辿れる整理単位を対象に、以下の手順1〜9をすべて行う。アクティビティのメンテ(ステップ5)は整理範囲に出てきたアクティビティだけに回す
- 全体モード(
--all): アクティビティ(active/shelved/snoozed)全域の棚卸しを行う。手順は references/full-inventory.md に従い、この本文の手順1〜9は回さない。アクティビティのメンテは全域に適用する
整理単位
整理単位は「2-3個のtopicを囲む形で増殖した関連A/D群」。入口がactivity/decisionでも、関連relationを辿ってtopicまで遡って整理する。
発動契機
実行は手動(ユーザーが「やるか」と言って初めて走る)。check-in時のナッジhint(tagスコープ内のdecision増分検知、全体モードは放置アクティビティ件数の検知)から誘導されることもある。実行コンテキストは限定しない: 別セッションで単独実行しても、sync-memoryの延長でやってもよい。
発話の例: 「/recompose」「recompose」「情報整理して」「まとめて」「リコンサイル」。全体モードは「/recompose --all」「アクティビティ棚卸しして」「activity棚卸し」「アクティビティの整理して」など。
次には発動しない: sync-memory標準形のStep 4a(セッション終了時の軽い自己完結処理)の自動棚卸し、単一アクティビティの完了・中断(activity-finish)、タグの共起分析・整理(tag-cleanup)。
手順
1. 入口の特定とスコープ提示
引数で entity_type + entity_id が指定されていればそのまま使う。指定されていなければ、文脈(check-in済みactivity・直近の話題・ナッジhintの対象tag)からエージェントが自律判断で決める。activity/topic/decisionどれでも可。
エージェントがスコープを切ったら、実行前にユーザーへ一行で規模感を提示してOK確認を取る。背景: CALMの記録内容はユーザー自身も把握していない前提なので、スコープの中身を見せる代わりに作業規模だけ示す。
提示フォーマット例:
「ざっと N activities + M decisions ぶん、SA X 人で並列整理する。これで進める?」 「整理単位が大きいので 2 cluster に分けて並走させる。SA Y 人。これで進める?」
提示する内容:
- 関連エンティティの概数(activities + decisions + materials の合計件数感)
- 並列起動する SA の人数(cluster 数で決まる、目安: 各 SA が 1 cluster を担当)
- 分割した場合はその数を明示
提示しないこと:
- どの activity/decision がどの cluster に入るかの内訳(ユーザーは記録を把握していない)
- 関連エンティティの個別 ID 一覧
OK が出たら自走モードに入り、以降ステップ2-8はユーザーへの追加確認なしで進める。OK が出るまでは記録 read のみで write はしない。
判断材料が本当にないとき(入口候補がゼロ)だけ「どこから整理する?」を聞く。
2. 全情報の収集
入口から関連エンティティを総ざらいする:
- 入口に応じた取得: activityなら
check_in、topicならget_decisions/get_logs、decisionならget_by_idsなどで起点情報取得 get_map(entity_type, entity_id, max_depth=3)で関連エンティティを辿る(depthが足りなければ運用で上げる)searchで言及されているが正式relationが張られていないentityを補完探索- 各エンティティのget系で全文取得(ページネーション、retract済みは除外)
フィルタ方針: retract済みdecision/logのみ除外。completedなactivityも収集対象に含める(間引き対象として扱うため)。
3. 統合materialの生成(anchor対応表付き)
サイズ予算
2,000〜3,000字を目安、最大5,000字まで許容(参考値、実運用で調整)。このmaterialはcheck-inのたびに全文注入されるため、予算超過は継続コストになる。check-in応答全体が予算を超えると、pin枠を超えた分から途中で切られる・スタブ化される(応答のnextフィールドにget_materialへのポインタが残る)ため、超えそうなら要約の密度を上げるか、整理単位の分割を検討する。
tagスコープとの対応
tagスコープとmaterialは原則1対1。1つのtagに複数のmaterialが必要になった場合は、materialを分けるのではなく1 material内にインデックスセクションを作り、深掘りは search / get_material へ誘導する(更新責務を曖昧にしないため)。
セクション構成
## 現状
(どこまで進んでいるか、今どのフェーズか。経緯の概観を含む)
## 合意事項
(有効なdecisionsの要約。各項目はWHAT + WHYで書く。
supersedes済みは除外。[議論中]タグのものは「残論点」に分類する。
次のエージェントがget_decisionsしに行かなくても判断の背景を
理解できる粒度で書く)
## anchor対応表
| 合意事項参照 | anchor型 | 検証先 |
|---|---|---|
| D#xxxx の要約 | 実装済 | src/services/foo.py:bar |
| D#yyyy の要約 | 未実装 | bar.py周辺 + D#zzzz の前後関係 |
## 注意事項
(検討して却下された代替案、議論中の制約条件、暗黙の関連 など)
## 残論点
(未解決の議論、次にやるべきこと、軽照合で見つかったズレ)
3-a. anchor自動推測
各合意事項について、エージェントが anchor型と検証先を推測する。型と書き方:
| 型 | 検証先 |
|---|---|
| 実装済 | 該当コードのファイル+関数 |
| 外部仕様準拠 | doc URL |
| 未実装 | 周辺の実装済みコード+関連decisionの前後関係 |
| 事実調査 | material内の一次ソース |
「最新decisionを静的参照」は採用しない。
推測できた合意事項は anchor対応表 に直接追加。推測できない / 確証が低いものは buffer に溜める。
3-b. anchor確定の対話
buffer が空でなければ references/anchor-setup.md の手順で、ユーザーと対話してanchor確定する。結果(mode=created)は anchor対応表 に merge する。
3-c. anchor対応表の統合
完成した anchor対応表 を material.content の「## anchor対応表」セクションに書き込む。
4. 軽照合
各合意事項について、anchorに対してSAに指示出ししてズレを確認する:
- 実装済 → 「このコード(パス)が、この合意(テキスト)と整合しているか確認して」
- 外部仕様 → 「このdoc(URL)が、この合意の根拠として通用するか確認して」
- 未実装 → 「周辺コード+関連decisionの前後関係から、この合意の方向で進めて問題ないか確認して」
- 事実調査 → 「このmaterialの一次ソースが、この合意の根拠として通用するか確認して」
SA(run_in_background)で並行実行。結果はマトリクス化して、合意との一致/ズレを記録。
- 一致 → そのまま維持
- ズレ → 「残論点」に追加。ズレが「anchor側が古い」起因なら anchor-setup.md の更新モードに回す候補としてマーク
5. リコンサイル(無効化・再編)
軽照合や情報棚卸しで「無効化・再編すべき」と判断したエンティティを、自律度ルールに従って処理する。
無効化・再編アクション(種別別)
- decision/log →
retract- 頻繁に参照される decision を無効化する場合は、単純な
retractより定型節 (書式は本スキル同梱のreferences/precedent-format.md)付きの新 decision でsupersedeし直すことを検討する。 retract は却下理由・射程の情報を残さないため、頻出参照の decision ほど supersede の価値が高い
- 頻繁に参照される decision を無効化する場合は、単純な
- material →
update_materialで上書き - topic/activity → retract非対応のため「直す」: status調整・合流・relation張り・新規作成
アクティビティのメンテ
整理範囲のアクティビティ(ステップ2で収集したもののうちcompleted以外。全体モードでは全域)について、goalと親への結びつけを整える。未定義や結びつけ漏れを一度に遡及せず、recomposeが呼ばれるたびにその範囲の分だけ直していく。
読み出しは get_goal(activity_id=...) と get_by_ids で行い、入口以外のアクティビティに check_in しない(statusがin_progressに変わり、作業中のセッションとしての記録も付くため)。
-
goalが未定義(
labelがundefined): 記録(description・log・関連decision)から真偽の付く終了条件が推せるなら、set_goal(activity_id, goal={"new": {"handle": ..., "statement": ..., "conditions": [...]}})で書く。条件にはClaudeが自力で到達できるもの(actor: "claude")を最低1本含める。既存の未判定goalの続きの作業だと分かるなら、新規作成せずset_goal(activity_id, goal={"goal_id": <そのgoalのgoal_id_raw>})で紐づける。推せない、または候補が複数で1つに絞れないときは何も書かない。未定義のまま残すのは正当な状態であり、雛形で埋めない -
不要印(
labelがnot_needed): 触らない -
条件の充足と判定: 記録からの推定だけで条件を
satisfiedにせず、judge_goalも呼ばない。外部の完了(PRのマージ等)はghなど実際の手段で確かめられた場合に限りsatisfiedに書く。goal付きアクティビティを閉じるのはupdate_activityではなくjudge_goal経由で行う -
親への結びつけ: 記録から、このアクティビティを子として振ったまとめ役のアクティビティが推せるなら、候補を提示せずそのまま結ぶ。結び先は直近の親のgoalにする(子の中で切り出された孫なら、まとめ役ではなく子のgoalに結ぶ)
get_goal(activity_id=<親のid>)で親のgoalを読む。未定義・不要印・判定済み(labelがclosed)なら結ばない- 親goalの
conditions[].boundにこのアクティビティが既にあれば何もしない update_goal(goal_id=<親のgoal_id_raw>, changes=[{"op": "add", "statement": "子「<子のtitle>」のgoalがachievedで閉じた(済にする前にget_goalで判定を確かめる)", "actor": "claude", "bound": {"type": "activity", "id": <子のid>}}])で条件を足す
誤った結びつけは条件をwaivedにして結び直せるので、ユーザーに確認しない。親が推せないときは何もしない
-
束ね役の親の提案(上の「親が推せないときは何もしない」の例外): どの親にも結べない未完了のアクティビティが、共通する素タグ(
domain:とintent:以外)で見て同じテーマで3本以上溜まっているときは、確認レーンに「常設の領域orchを立てて結ぶ」案を積む(子の候補とテーマを添える)。同じテーマかの判定に迷うものは提案に含めない。先に、そのテーマを束ねるorchが既にあるかをorch skillの「一覧」と同じ取り方で探す。同じ範囲に空席のorchがあれば新設せず、そこへ結ぶ(上の「親への結びつけ」に戻る)。無いときだけ提案し、了承を得たら、orch skillの「担い手空席の常設orchとして起票する」手順で立てて子を結ぶ。了承なしには立てない
自律度ルール(暫定・運用後見直し前提)
| ゾーン | アクション例 |
|---|---|
| 🟢 自律 | relation張り / status・title調整 / material上書き / アクティビティのメンテ(推せたgoalの作成・親goalへの条件追加) |
| 🟡 確証あれば自律 | decision/log retract / activity合流 |
| 🔴 確認 | 新規entity作成(material・アクティビティのメンテで作るgoalを除く) |
怪しき発火条件(全レーン共通で🔴に格上げ)
以下のいずれかに該当する場合は確認レーンに格上げする:
- 矛盾で新旧不明
- [議論中]タグ
- log に懸念明記
- 推測でしか判定不可
確認はバッファに溜めて最後に一括提示・ジャッジ。重大な矛盾だけはその場で確認(ハイブリッド)。アクティビティのメンテで終了条件や親が推せないものは、確認に回さず何もしない(束ね役の親の提案を除く)。
6. material の保存と tag pin
- 整理単位の代表tagを1つ選ぶ(例: 対象topicのdomainタグ、
recompose-context,anchor,reconciliationなどその整理単位を表すtag) - 既存material(同じtag + 対象エンティティへのrelation を持つ)を探す
- 既存あり: 上書き前のcontentを
add_logsで退避してから(履歴保全、バージョニング機構の代わり)、update_materialでcontent/title/tags/sourceを上書き - 既存なし:
add_materialで新規生成- タイトル:
recompose: {対象エンティティのtitle}(YYYY-MM-DD) - tags: 代表tag +
recompose-contextを含める relatedで対象エンティティに紐づける
- タイトル:
add_pin(source_type='tag', source_ref=<代表tag>, target_type='material', target_ref=<material_id>)で代表tagにmaterialをpinする- 複数ヒットした場合は警告を出してabort(正常系は1件のみ)
7. tag-notes更新
対象entityに紐づく全タグについて、以下を自問する:
- 追加型: 既存tag-noteに書かれていない横断知見はないか?同じタグを持つ他entityにも適用される教訓・運用ルールはないか?
- 改訂型: 既存tag-noteと矛盾する新しい合意はないか?→書き換え / 前提が覆った記述はないか?→削除or書き換え
書かないもの: 一過性の話題 / entity固有の文脈(→material行き)/ 既存記述と重複する内容
判定が出たタグは update_tag で上書きする。追記前に内容の種別を判定する: 教訓・落とし穴(行動を変える注意)と環境知識のみ全文で書ける。仕様スナップショット・運用手順・歴史記録は1行ポインタ(正典はコード/docs/decision/資材)に留め、状態・進行ジャーナル(「YYYY-MM-DD時点で〜中」等)は書かない。
既存notesの整理、または追記後(マージ後のドラフト)が天井(4,000字)を超える場合は、update_tagで書き込む前に demote_tag_notes(tag=..., sections=["見出しテキスト", ...]) で該当セクションを資材へ退避する(天井は「新しい長さが4,000字を超え、かつ既存より増加している」書き込みのみを拒否するため、現在は天井未満のタグでも追記で超える見込みなら先に縮める必要がある)。sections はnotes中の ## 見出しテキストで指定する(前文は退避不可)。mode は状態ジャーナル型のセクションのみ drop、それ以外は既定の pointer(退避後に1行ポインタを残す)を使う。整理の終了条件はdemoteの実行回数ではなく、返り値の notes_length.over_budget が false になったことで判定する。1タグ失敗でも他タグ処理は継続。該当なければスキップ。
8. relation補完
logs・decisionsの中で言及されているが正式relationが張られていないtopic/activity/materialを発見したら add_relation で補完する。
該当なければスキップ。
9. ユーザーへの報告
## recompose-context 完了: {対象エンティティのtitle}
### 統合material
- M#xxx(tag pin: <代表tag>)
### anchor対応表
- 合計N件(推測のみ N件 / 対話確定 N件 / 更新 N件)
### 軽照合
- 一致 N件 / ズレ N件(→残論点)
### リコンサイル
- 自律実行: N件
- 確認待ち: N件(バッファ提示)
### tag-notes更新
- (更新したタグ。なければ「なし」)
### relation補完
- (追加したrelation。なければ「なし」)
### アクティビティのメンテ
- goalを書いた N件 / 親に結んだ N件
確認待ちがあれば、報告後にユーザーと一括ジャッジする。
注意
- 鵜呑み防止ガード: 確証なく判断できないもの(矛盾で新旧不明 / [議論中] / log懸念 / 推測でしか判定不可)は自律retractせず確認レーンへ。重大な矛盾は手動運用ならその場で確認
- anchor推測の枠: anchorは「正解を当てる」のではなく「判断ができる場所を指す」だけで十分。「最新decisionを静的参照」は採用しない
- 情報を要約しすぎない。check-inだけで完結する密度が必要
- ステップ2〜8ではユーザーへのテキスト出力を最小限にする。最終報告(ステップ9)でまとめて伝える
- 自律度ルールは暫定。一度運用してから見直す前提
recording
セッション中に発生した「経緯(log)」と「成果物(material)」を記録する。判断基準と発動例をここに集約しているため、add_logs / add_material を呼ぶ前に本スキルの判定を必ず通す。
適用範囲
このスキルは初回 load 時に発動するが、判断基準は本セッション内のすべての後続ターンに適用される。以降のターンで下の例(L1-L5 / M1-M4)に該当する出来事が起きたら、明示的に skill を再発動せずとも add_logs / add_material を呼ぶこと。
sync-memory による漏れの救済は、ユーザーが /sync-memory を明示的に実行した場合に限られる(自動実行はない)。recording skill はトリガー例に基づく検知であり元々「完全網羅」を保証する仕組みではないため役割は「セッション中の見逃し低減」のままだが、事後の自動救済が無くなった分、判断に迷ったら記録する側に倒す姿勢がこれまで以上に重要になる。
対象
add_logs(経緯記録)add_material(成果物保存)
add_decisions / add_topic / add_habit は本スキルの案内対象外。
掲示板トピックへの投稿(board skillが扱うadd_logs呼び出し)も対象外。目的が自分の作業の経緯・成果物の記録ではなく他セッションへの伝達であるため、判断基準はboard skill側が持つ。add_logsツールのdocstringにある「呼び出し前にrecording skillの判断ガイドを通すこと」は、掲示板投稿以外の通常のadd_logs呼び出しに対する指示であり、この例外を妨げない。
CALM 自身の故障・使用感不満・既存記録との矛盾は add_logs ではなく report_signal を使う(下記「report_signal との切り分け」参照)。
発動例: add_logs(経緯記録)
| # | トリガー | 量の目安 | 残す内容 |
|---|---|---|---|
| L1 | 議論で 3 案以上比較 → 1 案採択(or 却下) | 議論で N 往復 / 案 3+ | 採択案・却下案・却下理由 |
| L2 | 実装/作業で blocked → 解決経緯 | blocked 1 回でも | 詰まった状況・解決手段・教訓 |
| L3 | PR レビュー対応で複数 fix した経緯 | bot 指摘 2 件以上 | 指摘内容・対応 commit・残課題 |
| L4 | ユーザー明示指示で方針が変わった | 1 回でも | 元方針・新方針・指示理由 |
| L5 | バグ観察(本題作業中の脇道発見) | 観察 1 件 | 現象・再現条件・影響範囲 |
発動例: add_material(成果物保存)
| # | トリガー | 量の目安 | 残す内容 |
|---|---|---|---|
| M1 | 設計たたき台 / ドラフト v0 / v1 完成 | 1 ドラフト | 生データそのまま(要約しない) |
| M2 | 調査・試算レポート完成 | 1 レポート | 試算式・結果・条件 |
| M3 | 未コミットのWIP差分・中間成果物 | 1 件 | diff・WIP 状態の説明 |
| M4 | 比較・分析結果(案 N 件の比較表など) | 表 1 つ | 比較項目・スコア・採択理由 |
「など」: 上記に当てはまらなくても、後続セッションが文脈を引き継ぐために要る経緯や成果物が出たら同等に扱う。例: 仕様確定議論の脇で出た代替案メモ、調査の途中で得た一次資料の抜粋、設計レビューで指摘された未解決リスト、外部記事の要旨など。
report_signal との切り分け(CALM 自身の故障・矛盾)
L5(バグ観察)はユーザーが取り組んでいる対象システムのバグが対象。CALM 自身の故障・使用感不満・既存記録との矛盾を観測したときは add_logs ではなく report_signal を呼ぶ(合意不要の生の観測データであり、topic 紐付けや文脈タグは不要)。
| kind | 発火例 |
|---|---|
machine_error | ツールエラー・hook 失敗・サーバー異常を観察した |
friction | 検索で引けるべき記録が引けなかった等、CALM の使い勝手への不満・違和感を感じた |
contradiction | 設計・実装中に既存 decision と矛盾する結論に達した / add_decisions の related_decisions、add_logs/add_material の related_records で矛盾に気づいた |
上記3種は頻出例であり、report_signal の kind は全9種ある(precedent_miss /
precedent_misapplied / boundary_case / rollback / goal_rollback /
guard_block を含む)。goal_rollback は update_goal の reopen_reason
(goal 判定の差し戻し)が、guard_block はhookのdeny判定が書く専用の kind で、
いずれも手で報告するものではない。全種の定義は report_signal ツールの
docstringを正とする。同一内容の再報告は report_signal 側で自動集約されるため、
迷ったら報告してよい。
より詳しい発動例・判断に迷う場合の追加基準は本スキルディレクトリ内の
references/taxonomy.md(1章・2章・4章)に整理してある。本ページの表と
食い違う場合は references/taxonomy.md を正とする。
記録の直後にgoalの条件を満たす場合
add_logs / add_material を呼んだ内容が、手元のgoalブロック(check_in等で読んで持っている場合)の未終端の条件を満たすなら、続けて update_goal を呼ぶ。changes に {"op": "set", "id": <条件id>, "state": "satisfied", "note": "..."} を積み、根拠になった decision や子 activity があれば同じ changes に {"op": "edit", "id": <条件id>, "bound": {"type": "decision"|"activity", "id": <id>}} を並べて束縛する(1回の呼び出しでまとめてよい)。
外部の事実(PRのマージ状況など)を根拠にする場合は、書く前にgh等で実際に確かめる。確かめたことが分かるように、その事実自体を add_material か add_logs として別途残す。推測のまま satisfied にしない。
update_goal の応答の goal.label が judge_ready(全条件が終端し判定待ち)になったら、そのまま持ち越さずその場で判定する。goal.open_questions に未決があれば畳むか1ターン聞き、そのうえで goal.terminal の充足が1件以上あれば judge_goal(goal_id, verdict="achieved", note=...)、0件なら judge_goal(goal_id, verdict="failed", note=理由) を呼ぶ。人間の判断は待たず、判定したことの報告もしない。
この判定の分岐(open_questionsの扱いからjudge_goalの呼び分けまで)はcheck-inの「goalフィールドの扱い」節を正本とする。判定条件が変わる場合はそちらを確認する。
優先方針
「多めに残す > 少なく残す」。
迷ったら記録する。漏れの最終救済はユーザーが /sync-memory を実行した場合の sync-memory が担うが、それは保証された安全網ではない。本スキルの役割は「セッション中の見逃し低減」であり、ここで取りこぼすと /sync-memory が実行されない限り文脈は失われたままになる。
呼び出し時の注意
add_logsの content /add_materialの content は要約せず生データを残すadd_materialの content 先頭 1-2 文は内容の説明・要約を書く(check-in 時に snippet として表示される)add_materialはadd_decisionsと違って「双方の合意」が不要。成果物が出た時点でユーザーに確認せず呼ぶadd_materialの content に事実と推論が混在する場合は明示的に区別する(例: 「【事実】」「【推論】」見出しを付ける)tagsにはdomain:を必ず付け、内容を表す素タグも追加する。intent:namespace の例:intent:discuss/intent:design/intent:implement/intent:investigaterelatedで関連する activity / topic / decision / log / material と紐付けるadd_logsはtopic_id必須。tag だけでは紐付かないadd_logs/add_materialのレスポンスにはrelated_records(類似する既存記録の上位3件。同一セッションで一度提示した記録は再提示されない)が付く。既存記録と矛盾・重複に気づいたらreport_signal(kind="contradiction")を呼ぶ
remember
【必須】ユーザーが記憶を依頼した。以下のフローで保存先を判定し、確認の規定(下表)に従って実行する。新規保存専用のスキルであり、保存済みの記録そのものの訂正・撤回は forget skillの担当。
この判定木は rule-placement skillの4軸評価(契機/型/リスク/改訂見込み)から導出された高速表である。日常の「覚えて」はこの判定木で足りる。判定木の末端で迷う場合、1つの依頼に性質の異なる複数ルールが混ざっている場合は、rule-placementのfull評価へ切り替える。本判定木を改訂するときは、rule-placement側の評価体系から導出できる形を保つこと(片側だけの改訂は禁止。導出関係が崩れていたら矛盾として扱う)。
発動契機
以下のいずれかで発動する。
- ユーザーが何かを覚えておくこと・保存すること・記憶に残すことを依頼した(「覚えて」「保存して」「これ残して」「忘れないで」「メモって」「記録して」など。表現のバリエーションは問わない)
- ユーザーの発言に既視感がある(下の「既視感による自律発動」。雑談レベルの繰り返しは対象外)
- ユーザーがこのセッションでのClaudeの行動・判断・出力を誤りとして直した(同じ指摘の繰り返し、「〜しないで」等。表現は問わない。人間の発話に限る)。まず直してから、本フローで教訓の置き場(フィードバックエントリを含む)を判定する
以下では発動しない(decision-record・forgetとの線引きは「## 注意」を参照)。
- 経緯・成果物の記録(recording skillの担当)
- メタask裁定の発効に伴う配置(rule-placement skillの担当)
確認の規定
| 書き先 | 扱い |
|---|---|
| rules・habits・CLAUDE.md・判例decision・新しいdecision | 候補ごとに承認を得てから書く |
| フィードバックのエントリとノート・auto-memory・tag-notes・pin | 書いたあと1行で報告する |
既視感による自律発動
ユーザーが明示的に記憶を依頼していなくても、発言に既視感を感じたら(雑談レベルの繰り返しは対象外)、判定フローの前処理3「既存を必ず引く」から始める(CALM searchだけで判定しない。get_feedback_entries、文脈内のauto-memory/habits/rulesの本文、触れたタグならtag-notesも見る)。
- どこにも見つからない → 勘違いとして扱い、以降の判定フローには進まず通常の応答に戻る
- 見つかったのが経緯(decision/log等)だけで、置き場所(フィードバックエントリ・auto-memory・habits・rules・tag-notes)には記録が無い → 新規保存として判定フローへ進む
- 置き場所に記録がある → 再発の手順(下)に進む
型の前判定(あらかじめ答えを出しておく1問)
そのルールは「〜な状態なら〜してよい/すべき」という条件付き判断基準か? (適用条件と適用外を書き分けられ、隣接文脈に誤適用したら害がある型。例外条項付きの禁止はこれではなく無条件規範)
- YES → 全文の正は判例decision(add_decisionsで記録。reasonに適用条件:/適用外:の定型節を含める。書式は本スキル同梱の
references/precedent-format.md。承認を得てから書く)と決まる。続けて下の判定フローで契機を判定し、契機の置き場が決まった場合はそこへ要旨と判例への参照を書く(両方配置。実行時は判例decision作成→参照配置の順。参照側の承認/報告は、置き場ごとの確認の規定に従う) - NO → そのまま判定フローへ
判定フロー
前処理として次を行う。
- 人間の発話による訂正・依頼か? 他セッションの中継だけなら発動しない
- 訂正なら先に直す。指示なら指示に従う(作業を先に済ませる)
- 既存を必ず引く
get_feedback_entries(数十件未満なら引数なしで全件)- CALM search(対象はdecision/log/material/topic/activityのみ)
- auto-memoryは文脈内の索引、habits/rulesは注入済みの本文、tag-notesは触れたタグなら注入済み。searchでは出てこないので、文脈を見る
そのルール/情報は…
├─ 訂正でも依頼でもない(置くべきルール・情報が無い)/一回きりの指示・訂正で、
│ 同じ型の再来が想定できない?
│ └─ YES → 記録しない(報告もしない)
│
├─ 引いた既存の記録が古い・誤っていて、消すか書き換える必要がある?
│ └─ YES → forget(新しい規範が要るなら、forgetの後にこの木へ戻る)
│
├─ 引いた既存の記録が今も正しく、それを踏んだ(再発)?
│ └─ YES → 再発の手順(下)
│
├─ 【型の前判定】条件付き判断基準か?
│ └─ YES → 全文の正本は判例decision(候補を出し、承認を得てから書く)。
│ 続けて下の枝で契機の置き場を決め、そこに要旨と判例への参照を書く
│ (両方配置)
│
├─ 特定のactivity/topicに取り組んでいる間だけ必要?(終われば不要)
│ └─ YES → pin(内容をdecision/materialとして記録し、add_pinで対象へ
│ 括り付ける。条件付き判断基準なら前判定で決めた判例decisionを
│ そのままpinで指す。指す先がmaterialか既存のdecisionなら書いたあと
│ 報告、新しいdecisionが要るなら承認。pin元へのcheck_inのたびに本文
│ ごと再配達される。ただしpinned合計が全体予算の枠を超えると、小さい
│ ものから優先して残り本文は先頭を残して切られ、続きへのポインタが
│ 付く縮退が起きる)
│
├─ 必要になる瞬間を字面で照合できる?
│ ├─ 人間の発話の字面 → エントリ(write_feedback_entry、strength=notify・
│ │ timing=utterance。書いたあと報告)
│ │ ※人間の発話に限る。SAの報告の中継・他セッションからのメッセージ・
│ │ バックグラウンドタスク通知・システム通知のターンは、hook側
│ │ (feedback_hook.py)が配達前に判定して止めるため、エントリ側に
│ │ 除外条件を書く必要はない。SAの報告や他セッションのメッセージを
│ │ きっかけにする教訓は、この判定で届かないので下の枝へ
│ ├─ 踏む直前に自分が言いがちな言い回し → エントリ(strength=notify・
│ │ timing=output、conditionのfieldは'text'。書いたあと報告)
│ │ ※次の区切り(次のUserPromptSubmit)で届く。止めはしない。人間の
│ │ 発話でないターン(bg・orchへの通知)にも届く
│ │ ※bodyは50字以内の一言。長い説明はrefに置く(拒否される)
│ ├─ ツール失敗のエラー文 → エントリ(strength=notify・timing=tool_fail。
│ │ 書いたあと報告)
│ │ ※CALM自身のMCPツールはエラーを例外でなく戻り値で返すため、
│ │ PostToolUseFailureとして届かない(CALMツールの失敗を踏み跡に
│ │ したいならこの枝は使えない)
│ │ ※PreToolUse hookにdenyされた呼び出しは、ツール呼び出し自体が
│ │ 実行されないためPostToolUseFailureが発火しない(公式hook
│ │ lifecycleの記述と、denyが多数発生した状況でも配達が一度も
│ │ 発生していない実機観察の両方で確認済み)
│ │ ※サブエージェント発(agent_type付き)の呼び出しにはhook側
│ │ (feedback_hook.py)が配達前に判定して止める
│ └─ 実行直前の引数でしか照合できない → blockのエントリ
│ (strength=block・timing=pre_tool。書いたあと報告)
│ ・実行直前にはblock(1回止め)しか無い。「知らせるだけ」は作れない
│ ・1回止める価値があるときだけ使う(見逃すと不可逆、または同じ罠を
│ 繰り返し踏む)。それ以外はエントリにせず、下の枝へ
│ ・tool名だけでallが空のblockは作らない(そのツールを毎回止めて
│ しまう)
│ ※エラーの前(設計時・着手時)に知っておくべきことなら、エントリは補助
│ にとどめ、下の枝を主にする
│
├─ 特定のファイルに触れる時だけ必要?
│ └─ YES → ~/.claude/rules/(パス付き。承認)
│ (条件付き判断基準なら、rulesには要旨+判例への参照を書く。
│ `cc-memory-habits.md`はhabits DBからの自動投影ファイルで手動編集
│ 対象外。対象はそれ以外の手動管理rulesファイル)
│
├─ 特定のタグ文脈でだけ必要?
│ └─ YES → tag-notes(update_tagで記録。書いたあと報告。条件付き判断基準
│ なら、tag-notesには要旨+判例への参照を書く。型が手順・事実参照
│ (仕様スナップショット・運用手順・歴史記録)なら全文を書かず
│ 1行ポインタに留め、正典はコード/docs/資材に置く(rule-placement
│ Step3のタグ文脈行参照)。追記後の見込み文字数が天井(4,000字)を
│ 超えるなら(現在天井未満でも増加更新は超過時に拒否されるため)、
│ 先に`demote_tag_notes`で縮めてから書き込む)
│
├─ どのプロジェクト・文脈でも常に適用される?
│ ├─ 条件付き判断基準(前判定YES)?
│ │ └─ 判例decisionのみで完結(承認。追加の置き場は作らない。契機を
│ │ 名指しできない条件付きは実質「自覚的な迷い」が契機であり、
│ │ 迷った瞬間のsearch/add_ask同梱のpullで届く判例が正しい置き場)
│ ├─ 「従え」系の無条件規範?(条件節なしの1文で書ける)
│ │ ├─ 毎回必ず守るべき(違反の実害が大きい)
│ │ │ ├─ 100字未満で書ける → habits(承認。add_habit後、
│ │ │ │ update_habitでtrigger_mode="always"へ昇格)
│ │ │ └─ 収まらない → ~/.claude/rules/(承認。横断ルール)
│ │ └─ 弱い行儀・好み → habits(承認。intelligently層のまま)
│ │ (intelligently層は実際には引かれにくい実測がある。
│ │ 本当に守らせたいものをここに置かない)
│ └─ 「知っとけ」系の文脈・tips?
│ ├─ 重要度高い → ~/.claude/CLAUDE.md(承認)
│ └─ 重要度低い → auto-memory(書いたあと報告)
│ (同じ趣旨の記録が再発したら、再発の手順(下)に従う)
│
└─ 次のいずれかに該当 → [rule-placement](../rule-placement/SKILL.md) のfull評価へ
・どれにも当てはまらない / 複数に該当して迷う
・1つの依頼に性質の異なる複数ルールが混ざっている
・契機が「あるツールを呼ぶ瞬間」「ある定型手順(skill)の実行」にしか
名指しできない(配置先がPR経路になり、fast pathの守備範囲外)
エントリを新しく書く手順
- bodyだけで意味が通るように、100字以内で書く。refは配達されない
- 長い手順は資材・skill・ファイルに置き、bodyに参照先を書く(例:「手順は資材〈名前〉をget_materialで読む」)
- refには「踏み跡: 〜」と経緯を書く。手入れのときに読むためのメモである
- 書いたら、名前と何をしたかを1行で報告する
- エントリの変更・削除はforgetを通さない
再発の手順(軽い出口)
まず、そのエントリが「届いた」かどうかを決める。
- 「届いた」とみなすのは、そのエントリの配達文が、今の自分の文脈に見えているときだけである。配達文は次のどれかの形をとる。
- 「過去の躓きから学んだ注意点」
- 「直前のツール失敗に関連する過去の躓き」
- 「直前の自分の発言に関連する過去の躓き」
- ブロックの理由文
- 見えていなければ「出なかった」とする。圧縮のあとや別のセッションでは、見えないので「出なかった」になる
- 訂正の語彙そのものを条件にしたエントリは、踏んだあとにしか届かない。このため「届いた/出なかった」の欄は空でよい
既存の記録の種類ごとに、次のことをする。複数の種類に同じ記録があるとき(例: フィードバックエントリとrulesの両方に同じ教訓がある)は、フィードバックエントリの行を必ず実行してstumbleを書き、他の行はそのうえで追加として行う。
| 既存の記録 | すること |
|---|---|
| フィードバックエントリ | add_feedback_note(kind="stumble")を書き、「届いた/出なかった」と「人に直されたか」を記す。出なかった: get_feedback_entries(name=)でread_markを取り、write_feedback_entry(action="update")で条件を広げる。広げれば次は届く見込みならここまでにする。広げても字面で拾えない型なら、次の「届いたのに」と同じく格上げを検討する。届いたのに踏んで人に直された: stumbleを1件書いた時点(再発1回)で、block化・rules/habits格上げ(要承認)・条件修正のいずれかを検討し、結果をnoteに残す。件数が溜まるのを待たない。 |
| auto-memory / tag-notes | 字面で照合できる: エントリを新しく作る(書いたあと報告)。bodyはその記録の要旨とし、「詳細は〈記録名〉」と書く。 照合できない: まず「それを踏む直前に、自分が言いがちな言い回しはあるか」を考える。あれば、その言い回しを条件にしたoutputのエントリを新しく作る(書いたあと報告。上の「字面で照合できる」と同じ作り方で、bodyは50字以内)。言い回しが思い当たらないときだけ、その記録に日付つきで再発の1行を追記する。書式は - 再発 YYYY-MM-DD: <何が起きたか1行>(書いたあと報告)。再発の行を1行追記した時点(再発1回=2回目に踏んだ時点)で、rule-placementのfull評価で格上げ先を決める。結論がrules・habits・CLAUDE.md・判例decision・新しいdecisionなら、下の「格上げの承認の取り方」に従う。tag-notes・pin・エントリなら書いたあと報告する。 |
| rules / habits / CLAUDE.md | 字面で照合できる: blockかnotifyのエントリで強制力を足す(書いたあと報告)。bodyは人間の規則への参照だけにし、規則の中身を言い換えない。 照合できない: auto-memoryに「〈規則名〉の再発」の記録を作るか追記して、上の行と同じく再発の行を1行書いた時点でfull評価に進む。 すでに常時push(always/rules)に置かれていて上げる先が無いときは、書き直しの候補を出し、下の「格上げの承認の取り方」に従う。 |
照合できない再発は、この1本の道だけで扱う。full評価に進むのは、再発の行を追記して格上げを検討するときだけである。
格上げの承認の取り方
格上げ先が承認の要る置き場(rules・habits・CLAUDE.md・判例decision・新しいdecision)になったときは、次の2通りのどちらかで承認を取る。
- 生きたセッションでユーザーがいる: その場で候補を出して聞く
- 人がいない場面(sync-memoryなど、セッションを閉じる直前の一括処理):
add_askでメタask(kind="meta"、blocks不要)を起票する。questionは「教訓〈名前〉を〈候補の置き場〉へ格上げしてよいか」とし、contextには教訓の要旨・踏んだ経緯・候補の置き場とその理由を入れる。起票までが仕事で、承認なしに書かない
格上げ則(判定フローに優先する例外)
「見逃すと不可逆な事故になる(外部へのpush・データ消失・他セッション巻き込み)」かつ「踏む直前に迷いが発生しない(良かれと思って・ついでに踏む)」ルールは、pull系(判例decision・habits intelligently層・auto-memory)に置いてはいけない。契機を名指しできるならその契機のpush経路(tag-notes/pin)、できないなら常時push(habits always昇格 or ~/.claude/rules/)へ格上げする。pull経路は実際には引かれないことがある。
- 実行直前の引数で照合できるなら、blockのエントリを格上げ先の最上位にする
- 既存のエントリがあっても、それが不可逆で、しかも気づかずに踏む種類なら、blockのエントリを新しく作ることを同時に検討する
格上げ先の経路の判断に迷う場合は、fast pathで即決せずrule-placementのfull評価(Step 4の強度補正)で確定する。
判定の3軸(fast path版)
- 契機: 何が起きたらこのルールが要るのか。作業単位 → ファイル → タグの順(狭い契機から)に名指しを試し、名指しできないものだけを「常時」に落とす。複数の契機に該当したら、より狭い契機を採る。「重要だから常時」は契機の名指しの失敗(重要度はリスク軸で扱う)
- 型: 無条件規範(従え系)/ 条件付き判断基準(〜ならOK系)/ 事実・tips(知っとけ系)
- リスク: 見逃しコスト × 無自覚性。上記の格上げ則を参照
habits投影の仕組み
add_habitで記録したhabitは常にtrigger_mode='intelligently'(マニフェスト表示)で作成される。SessionStart時に~/.claude/rules/へ自動投影されるが、intelligently層はタイトルのみで、全文はget_habitsでのon-demand取得が必要になる。
「毎回必ず全文で見てほしい」レベルの制約は、記録後にupdate_habitでtrigger_mode="always"へ昇格する追加ステップが要る(新規作成と同時にalways指定はできない)。判定に迷う場合はユーザーに確認する。
注入の強度
強 ┃ habits(always層) — 全文をSessionStartで常時投影。絶対守れ
┃ rules/ — セッション起動時に全文注入。従え
┃ pin — pin元へのcheck_inのたび本文ごと再配達
┃ (pinned合計が予算超過時は小さい順に優先、
┃ 溢れた分は先頭を残して切られポインタが付く)
┃ フィードバックエントリ — 字面が一致した瞬間に配達、blockは実行を止める
┃ tag-notes — タグ文脈に触れた初回に全文注入
┃ CLAUDE.md — プロジェクト文脈として参照
┃ 判例decision — search/pull_precedents/add_ask時にpullで届く
┃ auto-memory — 見えてはいるけど、気づけば使え程度
┃ habits(intelligently層) — タイトルのみ常時投影、全文はget_habitsで取得
弱 ┃
注意
- 判定に迷ったらrule-placementのfull評価へ。それでも決めきれない場合はユーザーに確認する
- 「決めたことの事実記録」としてのdecision(decision-record skillの担当)は「覚えて」の対象外。ただし条件付き判断基準の配置先としての判例decisionは本フローの正規の出口であり、対象外ではない。記録時はdecision-recordの書式作法(定型節)に従う
- auto-memoryとCALMの二重記録はOK(異なる注入経路として機能する)
- 保存済みの記録そのものが古い・誤りで消す・書き換える必要がある場合は対象外。気づいたらforget skillへ
restart
CALMのローカルMCPサーバー(52837)を強制的に再起動する。
PRマージ後の後片付け全体(worktree削除やgit pull等)はリポジトリのCLAUDE.mdの手順に従う。本スキルはサーバーの再起動だけを行う。
launcherの通常起動は「生きていれば何もしない」ensure動作のため、プラグインをアップデートした後もコード変更が反映されないことがある。このスキルは既存プロセスを明示的に終了させてから新規プロセスを起動する。
embeddingサーバー(52836)はMCPサーバーの再起動より前に必ず停止する。新しいMCPサーバーが起動直後に自動でembeddingサーバーを立ち上げて温めるため、embedding側のコード変更も反映される。
再起動の前
打ってよいのは次の2つのときだけ。
- このセッションでCALMのPRをマージした後や設定を変えた後で、反映を待っている作業や確認があるとき
- CALMが古い版のまま動いていて困っているとき
反映を待つものが無いなら、claude plugin update calm@calm-marketplace で更新だけして、再起動はサーバーの陳腐化 watchdog に任せる。watchdog は処理中の呼び出しが0件になるのを待って自動で再起動する(確認間隔は CALM_STALENESS_CHECK_INTERVAL_SEC、既定1時間)。設定を変えただけでコードの更新が無いときは、更新は省いてよい。
- 他のセッションが書き込み中かもしれないので、
claude agents --jsonで生きているセッションを確かめる。確認は人に求めず、そのうえで自分の判断で進める claude plugin update calm@calm-marketplaceを実行する- 古い窓口から打たない: 次で
mcp_server.started_atを確かめ、直近の再起動より後の時刻であれば、別の窓口が既に打った後なので打ち直さない
Bashツールは呼び出しをまたいでシェル変数を引き継がず、セッションの ${CLAUDE_PLUGIN_ROOT} は更新前の版を指したままのことがある。そのため以降のコマンドは、同じ呼び出しの頭で更新後の版のディレクトリ(installed_plugins.json の user スコープのエントリ)を取り直し、空なら止める。
PLUGIN_DIR=$(jq -r '[.plugins["calm@calm-marketplace"][] | select(.scope=="user")][0].installPath // empty' ~/.claude/plugins/installed_plugins.json) && [ -n "$PLUGIN_DIR" ] && uv run --directory "$PLUGIN_DIR" python "$PLUGIN_DIR/scripts/restart_server.py" --status
新しい版のディレクトリは依存が未同期のことがあるため、--no-sync は付けない(uv run が先に同期する)。同期に失敗してコマンドが落ちたら、再起動はせず中断し、出力をそのまま報告する。
実行
上の条件を満たしたら、確認は取らずに以下をBashツールで実行する。
PLUGIN_DIR=$(jq -r '[.plugins["calm@calm-marketplace"][] | select(.scope=="user")][0].installPath // empty' ~/.claude/plugins/installed_plugins.json) && [ -n "$PLUGIN_DIR" ] && uv run --directory "$PLUGIN_DIR" python "$PLUGIN_DIR/scripts/restart_server.py"
外から終了させるため、watchdog の「処理中の呼び出しが0件になるまで待つ」ガードを通らない。停止の直前に処理中だった書き込みは、失敗に見えても DB には書かれていることがある。再起動の前後で失敗に見えた書き込みは、リトライする前に検索で記録があるかを確かめる(確かめずに再送すると重複する)。
直後
既存のセッション(bgを含む)は通常、再接続の操作なしでつながり直すため、/mcp の再接続や bg の stop→respawn は要らない。呼び出しが固まったセッションがあったときだけ、次のとおり対処する(固まったかどうかの見分け方は末尾の節)。
- 窓口(対話セッション): そのセッションで
/mcpからreconnectする。直らなければそのセッションを再起動する - bg:
claude stop <id>で止め、claude respawn <id>で会話を引き継いだまま起こし直す(依頼文の再送は不要)。respawnで短い参照(id)が変わることがあるので、SendMessageは新しい参照へ「get_configを呼んで疎通を確認して」と伝える。claude stopがauto modeのclassifierに止められたら、迂回せずユーザーに! claude stop <id>を頼む - 起こし直したbgがorchの子なら、そのorchの窓口へ
SendMessageで「bgを起こし直した」と伝える(窓口の説明に書かれたbg一覧を直すため)
結果の報告
スクリプトはJSON形式で結果を標準出力に返す。
uv_sync.okがfalse: 依存関係の同期に失敗している。detailを伝えつつ、mcp_serverの再起動自体は実行済みなのでその結果と合わせて報告するmcp_server.okがtrue: 再起動成功。old_pids(旧プロセス)とnew_pids(新プロセス)をユーザーに簡潔に伝えるmcp_server.okがfalse: 再起動失敗。detailの内容をそのままユーザーに伝え、--statusでの手動確認を促す。プラグイン更新直後の初回実行はvenv再構築が重く、稀にこのタイムアウトが起きることがある。その場合は再実行を促すembedding_server.stopped_pidsは停止したembeddingサーバーのPID。空配列なら元々停止していただけなので触れなくてよいcachesは削除したパスの記録。特に問題なければ触れなくてよいorphaned_processes.stoppedが空配列でない場合: 削除済みのプラグインディレクトリから動き続けていたプロセス(embeddingサーバー・MCPサーバー本体等)を検出して停止したことを伝える(pid・cwdで何を止めたか分かる)。launcherプロセス(各セッションのブリッジ)は対象外で、この一覧に出てくることはない。orphaned_processes.keptは、同種のプロセスのうち起動元ディレクトリがまだ存在していた(=孤児ではない)ものの記録で、特に問題なければ触れなくてよいplugin_cache_pruneはプラグインキャッシュ旧バージョンの掃除結果(removed/skipped)。削除件数があれば一言触れる、空配列なら触れなくてよい
再起動の後
CALMのツールが通るのを確かめてから、退避してあった分を流し込む。
- CALMに書けなかった間の記録を退避ファイルに書き出していた場合は、再起動の後に自分の分だけを名指しして流し込む。持ち主が生きていない分(respawnで消えたbg、閉じた窓口の分)は、中身を確かめてから名指しで流す。ディレクトリ直下を一括で流すような操作は行わない
- bgを起こし直した場合は、空席のorchの説明に書かれている、生きているbgの一覧(あれば)を、実際に起こし直した内容に直す
- 反映待ちは
--statusのmcp_server.started_atとマージした時刻を突き合わせて確かめ、済んだものは消す
固まった接続の見分け方
自動でつながり直さなかった場合の例外として、再起動の前からいた接続が古いサーバーを掴んだままのことがある(対処は「直後」の節)。エラー文言がauto modeのclassifierの拒否のように見えても、実際は古いサーバーへの接続が固まっているだけのことがある。--status の mcp_server.started_at が今回の再起動時刻より前なら、その接続は古いサーバーを掴んだままだと分かる。
rule-placement
一般化ルールの配信先をfull評価で決める。remember skillの判定木はこの評価体系から導出された高速表であり、本skillはその一般解。分解 → 4軸評価 → 承認要否の仕分け → 承認不要分の実行と報告 → 配置計画の提示(承認が要る分のみ) → ユーザー確認 → 実行、の順で進める。
- 入力: メタask裁定のanswer_body、またはremember/forget/auditから持ち込まれたルール群
- 出力: 承認が要る配置だけの配置計画表(ルール × 配置先 × 根拠となる軸の値)。承認が要らない配置は先に実行し、まとめて1行で報告する
発動契機
以下で発動する。
- メタask(kind="meta")の裁定をtriage_askでpromoteする直前(必須)
- remember skillの判定木の末端で迷った場合
- 1つの裁定・依頼に性質の異なる複数ルールが混ざっている場合
- forget/audit中に既存配置の再配置を検討する場合
- remember skillの再発の手順で、照合できない再発の行を追記し(再発1回)格上げを検討する場合
以下では発動しない。
- remember skillのfast pathで判定できる日常の単純な「覚えて」
- 議論の合意事実の記録(decision-record skillの担当)
Step 0: 分解する
裁定・依頼の本文を読み、撤回単位ごとにルールへ切り出す。切り出し基準は「このルールだけを撤回したくなる場面があるか」。あるなら別ルール。人間の裁定は自然言語の一続きで返るため、性質の異なる複数ルールが1本に同居しているのが通常である(1件の裁定が7ルール・5配置先に分かれた実例がある)。以降のStepは各ルールに対して個別に実行する。
Step 1: 配信するか(0次分岐)
| 判定 | 出口 |
|---|---|
| 一回性の判断で、同型の再来が想定できない | 何もしない(askのanswer_bodyに残っていれば十分) |
| 将来の別用途の素材で、今のエージェントの振る舞いを変えない | add_materialで保存のみ(配信経路に乗せない) |
| 今後のエージェントの振る舞いを変える | Step 2へ |
Step 2: 4軸を評価する
軸1: 契機 — 何が起きたらこのルールが要るか、その出来事に名前を付けられるか
上から順に(具体的な契機から)試し、どうしても名指しできないものだけを「無契機」に落とす。「重要だから常時」は契機の名指しの失敗であり、重要度は軸3で扱う。
| 値 | 見分けの問い |
|---|---|
| 自覚的な迷い | エージェントが「これでいいのか」と詰まって検索・確認する場面か |
| 定型手順の実行 | 「ある決まった作業を始めた瞬間」と言い切れ、対応するskillが実在するか |
| 字面で照合できる瞬間 | 人間の発話・ツール失敗のエラー文・実行直前の引数のどれかの字面で、validatorを通る条件式(tool一致+regex/len_gt、最大3要素)を書けるか |
| ツール呼び出し | 「あるツールを呼ぼうとした瞬間」と言い切れるか |
| 作業単位 | 特定のactivity/topicに取り組む間だけ要り、終われば不要か |
| ファイル文脈 | 「特定のファイル/パスパターンに触れる時」と言い切れるか |
| タグ文脈 | 要る場面に共通して付くタグ(domain:等)を1つ挙げられるか |
| 無契機 | 上のどれも名指しできない |
作業単位の枝は寿命も判定するので、判定木では先に切る。
軸2: 型 — このルールを1文で書くとどの文型か
| 値 | 文型 | 罠 |
|---|---|---|
| 無条件規範 | 「〜する/〜しない」 | 「XをやるならYを先に」という順序制約は手順ではなくこれ。例外条項付きの禁止もこれ(例外は規範本文に含める) |
| 条件付き判断基準 | 「〜な状態なら〜してよい」 | 適用条件と適用外を書き分けられ、隣接文脈への誤適用に害がある型のみ。判断そのものを条件に委ねる型を指す |
| 手順 | 「まず〜、次に〜」 | 順序に意味があり、1ステップ抜き出すと意味を失うもの |
| 事実・参照 | 「〜である/〜にある」 | 行動を指示しない知識 |
軸3: リスク — 見逃しコスト × 無自覚性
- 見逃しコスト: 高 = 外部にpushされる・データが消える・他セッションを巻き込む・不可逆 / 中 = やり直しに人手と時間がかかるが復旧可能 / 低 = その場の修正で済む
- 無自覚性: 自覚あり = 踏む直前に立ち止まる型(pullでも届く)/ 無自覚 = 良かれと思って・ついでに踏む型(pushでないと届かない)。過去に「本人が問題と思わず踏んだ」事故記録があれば無自覚と判定してよい
軸4: 改訂見込み — 半年後も同じ文面か
高 = 例外条項が増えそう・数値/閾値/パス/ツール名を含む・実装の現状を記述している / 中 = 方針は安定、表現調整はありうる / 低 = 原理レベルで書き換える理由が想像できない。初回裁定は「高」と見るのが安全側(同型N件が根拠なら、N+1件目で例外が見つかる余地が残る)。
Step 3: 一次候補を引く(軸1 × 軸2)
| 軸1\軸2 | 無条件規範 | 条件付き判断基準 | 手順 | 事実・参照 |
|---|---|---|---|---|
| 無契機 | habits always(100字未満なら)/ rules | 矛盾のサイン(エッジ表E1へ) | rules(順序制約だけ切り出す) | habits intelligently / auto-memory(重要度低い)/ ユーザーCLAUDE.md(重要度高い) |
| タグ文脈 | tag-notes | tag-notes(要旨+参照)+判例decision(定型節を持てる判例側が正) | tag-notes(1行ポインタ。全文の正典はコード/docs/資材) | tag-notes(1行ポインタが既定。そのタグ固有の環境知識のみ全文可) |
| ファイル文脈 | rules(パス付き) | rules(パス付き、要旨+参照)+判例decision(定型節を持てる判例側が正) | rules(パス付き) | rules(パス付き) |
| 作業単位 | pin | pin(判例decisionをpinで指す) | pin(手順materialをpinで指す) | pin |
| 字面で照合できる瞬間 | フィードバックエントリ(実行直前ならblock) | フィードバックエントリ(要旨+参照)+判例decision | フィードバックエントリ(bodyに参照先) | フィードバックエントリ |
| ツール呼び出し | docstring | docstring(要旨+参照)+判例decision | docstring | docstring |
| 定型手順の実行 | skill | skill(要旨+参照)+判例decision | skill | skill |
| 自覚的な迷い | 型の再検査(迷いが発生するなら無条件ではない) | 判例decision | 判例decision+material | 判例decision |
ツール呼び出し→docstringは、ツールの契約そのものに限る(それ以外は上の「字面で照合できる瞬間」の行を使う)。
条件付き判断基準の複合配置(「X+判例decision」のセル)はすべて同じ規則の適用である: 全文の正は定型節を持てる判例decision側に置き、契機側の経路には要旨と判例への参照を書く。ファイル文脈のrules配置は、注入自体はセッション起動時の常時pushであり、パスは適用判断のスコープ注記である(発火条件ではない)。
タグ文脈×手順・事実参照のセルは、tag-notes自体には全文を置かない。demote_tag_notesが正典として持つ記述規約(教訓・落とし穴と環境知識のみ全文、仕様スナップショット・運用手順・歴史記録は1行ポインタ、状態・進行ジャーナルは0行)に従う。
Step 4: 軸3で強度を補正する
| 状況 | 補正 |
|---|---|
| 一次候補がpull系(判例decision / habits intelligently)で、軸3が高×無自覚 | push系へ格上げ。契機を名指しできるならその契機のpush経路(tag-notes/pin/docstring)、できないなら常時push(habits always / rules) |
| 一次候補が常時pushで、軸3が低 | 降格を検討。常時枠は最も高価な資源であり、契機の名指しをやり直す |
| 一次候補がtag-notesで、軸3が高 | pinへの格上げを検討(tag-notesはセッション内初回のみ、pinは毎check_in再配達) |
| 契機の字面が照合できる | フィードバックエントリを格上げ先にする。実行直前の引数で照合でき、リスクが高いならblockを最上位にする |
「迷ったら弱い経路(判例decision)へ」という既定は軸3が中以下のときのみ使える。高×無自覚のルールは、契機を名指しできなくても常時pushへ置く。pull経路が実際には引かれていなかった実測があるため、高リスクをpull任せにしない。
Step 5: 軸4と容量で除外する
| 状況 | 対応 |
|---|---|
| 一次候補がskill / docstring / server instructionsで、軸4が高 | 不可。安定するまでtag-notesまたは判例decisionで運用し、改訂が止まってからPR経路へ移す。移動時に元の配置を撤回する(両方に残さない) |
| 一次候補がhabits alwaysで、100字未満に収まらない | rulesへ。撤回・監査が手動になる負債を配置台帳に明記する |
| 一次候補がhabits alwaysで、alwaysプールに空きがない | 既存always habitの降格とセットで検討。降格候補が無ければrulesへ(昇格ゲートと容量の実装値はhabit_service/configを参照) |
| 改訂見込みが高く、ツールを契機とするルール | docstringではなくフィードバックエントリで運用する(実行直前はblockのみ) |
経路カタログ(判定の参照用)
| 経路 | 発火点 | 確実性 | 改訂コスト | 向く型 |
|---|---|---|---|---|
| rules | セッション起動時に全文注入 | 最高(push常時) | ファイル編集で即時。ただしDB外で監査対象から漏れやすい。パス付き見出しでファイルスコープを表現する慣行がある(適用判断は本文の対象パス記述で行う) | 全型 |
| habits always層 | 同上(投影ファイル経由) | 最高(push常時) | ツールで即時 | 無条件規範のみ(1件100字未満) |
| habits intelligently層 | タイトルのみ投影、全文はon-demand | 低(pull。引かれない実測あり) | ツールで即時 | 弱い行儀 |
| auto-memory | 索引が文脈に見え、本文はpullで読む | 低(pull) | ファイル編集で即時 | 重要度の低い事実・tips |
| tag-notes | タグに触れるツール呼び出し時(セッション内初回のみ) | 高(push契機付き) | 全文置換で即時(天井超過時の縮小はdemote_tag_notesでセクション単位に退避) | 全型(ただし全文可は教訓・落とし穴と環境知識のみ。手順・仕様・歴史は1行ポインタ、状態ジャーナルは不可) |
| pin | pin元へのcheck_inのたび毎回、指す先の本文ごと(ただしpinned合計が全体予算の枠を超えると小さい順に優先され、溢れた分は先頭を残して切られポインタが付く縮退が起きる) | 高(push契機付き) | ツールで即時 | 全型(既存エンティティを指す) |
| フィードバックエントリ | 人間の発話・ツール失敗・実行直前の字面が一致したとき(実行直前はblockのみ) | 高(契機つきpush)。ただし同時に届くのは最大3件で、idの若い順に打ち切るため、後から作ったものほど落ちやすい | ツールですぐ直せる | 本文だけで意味が通る100字の要旨。どの型でもよい |
| 判例decision | search / pull_precedents / add_ask時の類似判例同梱 | 中(pull。add_ask同梱は強制発火点) | supersedeで置換 | 条件付き判断基準(定型節の書式は本スキル同梱の references/precedent-format.md) |
| skill | そのskillの発動場面 | 中(発動条件の記述精度に従属) | PR+デプロイ | 手順 |
| ツールdocstring | ツール呼び出しの瞬間 | 高(push。契機が最も鋭い) | PR+デプロイ | 短文の規範・判断基準 |
| server instructions | MCP接続中の全セッションに常時 | 最高(push常時) | PR+デプロイ | 無条件規範の要約 |
エッジケース
| 状況 | 扱い |
|---|---|
| E1: 無契機なのに条件付き判断基準 | 矛盾のサイン。条件の成立を判定する場面が契機になるはずで、名指しし直す。出てこないなら条件節が飾りで実質は無条件規範であることを疑う |
| E2: 契機は鋭いが、その契機を持つ経路が無い(Bash実行の瞬間等) | 字面で照合できるならフィードバックエントリ。実行直前はblockに値するときだけ。照合できなければ従来どおり(軸3が高なら常時push(rules)、低〜中なら判例decisionでpull任せ)。新規の配信機構は提案しない |
| E3: 複数の契機に等しく該当する | 分解を疑う。分解できないなら狭い契機を採り、広い方は参照で繋ぐ |
| E4: 既存の配置物と同趣旨がある | 新規配置せず既存へ合流する。重複配信は撤回時に片方が残る事故を生む |
| E5: 判定に確信が持てない | 既定は判例decision(誤配置の害が最小で後から昇格できる)。ただし軸3が高×無自覚なら使わない。確信度が低いことをreasonの適用条件節に残し、再来時に見直す |
| E6: 裁定が「今は決めない」型 | 配信しない。[議論中]decisionとして残す |
実行
- 各配置を承認要否で仕分ける。rules・habits・CLAUDE.md・判例decision・新しいdecisionは承認が要る。フィードバックエントリ(ノートを含む)・auto-memory・tag-notes・pinは承認が要らない
- 承認が要らない配置は、各配置の実行前に配置先の既存内容に同趣旨の記述が無いか確認したうえで(あれば合流。この確認が中断からの再実行時の冪等性も兼ねる)、先に実行する。実行し終えたら、まとめて1行で報告する
- 承認が要る配置だけを配置計画表(ルール要約 × 配置先 × 根拠となる軸の値)にまとめ、ユーザーに提示して確認を取る
- 確認が取れた配置を、既存内容の合流確認を経て実行する。即時反映経路(habits / tag-notes / pin / 判例decision / rules / CLAUDE.md / フィードバックエントリ)はその場で実行する。PR経路(skill / docstring / server instructions)が結論になった場合は、その場で書かず実装タスクとして切り出しユーザーに委ねる
- メタask裁定の発効の場合は、配置完了後にtriage_askのpromoteで締める(次節)。promote自体は、個々の配置の承認要否によらず必ずユーザーの確認を挟む
メタask発効時のtriage_ask接続
kind="meta"のaskをpromoteする場合:
- 配置の実行を先に済ませ、
triage_ask(action="promote")を最後に呼ぶ。promoteが発効のコミットに相当する(先にpromoteすると、中断時に配置漏れがpromoted表示の裏に沈黙する) - promoteで生成するdecisionは「発効の裁定記録」1件とする
- decision: 発効した一般化ルールの型(「◯◯型の問いは今後、判例に従って自己裁定してよい」等)
- reason: 裁定の根拠(判例N件の一貫性等)に続けて配置台帳を書き、そのあとに定型節(適用条件:等)を置く。台帳は定型節より前に置く(定型節の後ろに置くと箇条書きが直前の節の項目として解釈される)
配置: - <ルール要約> → <配置先>(<識別子またはパス>) - <ルール要約> → 非配信(material保存のみ)
- 個別ルールのうち判例decision行きのものは、promote前にadd_decisionsで個別に作成し、そのIDを台帳に記載する
- rules / CLAUDE.mdなどDB外への配置は台帳に必ずパスを残す(forget/auditの棚卸しはこの台帳を手がかりにする)
- dismissする場合は現行運用のまま(本skillの配置フローは通らない)
scribe
CALMの記録(decisions, logs, materials)を元に、外部共有可能なドキュメントを生成する。
関連skillとの境界
- 「この議論を書き出して」「設計ドキュメントに起こして」のような、記録を外部共有用の文書にする依頼で使う
- 記録の整理・統合(recompose-context)と教訓抽出(postmortem)では発動しない
1. 対象アクティビティの選択
- 引数で
activity_idが指定されていればそのまま使う - 指定されていなければ
get_activities(status="completed")で候補を表示し、ユーザーに選んでもらう - 候補一覧はタイトルのみで提示し、内部IDは表示しない
- 複数のアクティビティをまとめて1つのドキュメントにすることもできる。ユーザーに確認する
2. [執筆]アクティビティの作成
対象が決まったら、ドキュメント生成作業を追跡するアクティビティを作成し、check_in する。
- タイトル:
[執筆] {仮タイトル}(構成確定後にupdate_activityで更新する) - タグ:
intent:document+ ソースアクティビティのdomain:タグを引き継ぐ - description: ソースアクティビティのIDと目的を記載
3. 素材の収集
ソースアクティビティごとに以下を収集する:
check_in(activity_id=...)でアクティビティ情報を取得- check-in結果の
context.topicsからtopic_idを取得する get_decisions(entity_type="topic", entity_id=topic_id)で決定事項を取得get_logs(entity_type="topic", entity_id=topic_id)で議論経緯を取得search(entity_type="material")/get_materialで資材を取得
必要に応じて、ソースアクティビティのタグで search し、関連する別トピックの情報も補足的に収集する。
4. ボリューム判断と構成
収集した素材の量を確認する。
通常の場合: そのままドキュメント1本として書く。構成案を提示してユーザーの確認を取る。確定したらアクティビティのタイトル・descriptionを更新する。
ボリュームが大きい場合: 分割が必要と判断したら、分割案を提示してユーザーとすり合わせる。合意後、各ドキュメントに対して追加の[執筆]アクティビティを add_activity で作成する。
5. 執筆
intent:document のtag notesに従ってドキュメントを生成する。
tag notesが未設定の場合のデフォルト構成:
---
date: {日付}
source_activities: [{activity_id一覧}]
---
# {タイトル}
## 背景
{なぜこの決定が必要だったのか。動機・制約・前提条件}
## 決定事項
{何を決めたか。具体的な内容}
## 代替案と却下理由
{検討したが採用しなかった選択肢と、その理由}
重要なルール:
- CALMにアクセスできない読者を前提とする。内部ID(decision #123等)を参照せず、内容を直接記述する
- ソースが不足している箇所には
<!-- TODO: 要確認 -->マーカーを付けて書き進める - ドキュメント間参照はファイル名で行う
6. 出力と確認
- 生成したドキュメントをユーザーに提示する
- ユーザーのフィードバックを受けて修正する
- 最終確認が取れたらファイルに書き出す
- [執筆]アクティビティをcompletedにする
- 分割ありの場合: 残りの[執筆]アクティビティの存在をユーザーに伝える
注意事項
- ユーザーの確認なしに書き始めない。構成案の合意を必ず取る
- 「スキルは骨組み、tag notesは味付け」の原則に従い、執筆時の振る舞いの詳細はintent:documentのtag notesに委ねる
- エクスポート先のファイルパスは必ずユーザーに確認する
setup
セットアップと設定変更の窓口。自分では何も書き込まず、やりたいことを判断して振り分け先に渡す。
振り分け
何をしたいかを一言宣言してから振り分け先へ進む(例:「CALMの設定変更として進めるね」)。違っていればユーザーがここで訂正できる。判断がつかないときだけ、やりたいことを普通の言葉で聞く。
| やりたいこと | 振り分け先 |
|---|---|
| CALMをインストールした直後で、動く状態か確かめたい・使い方を知りたい | initial-setup |
| 新しいプロジェクト・取り組みをCALMに登録したい | project-setup |
| 環境変数で動作を調整したい(件数・間隔・予算など) | env-config |
迷う組み合わせ: インストール直後に「プロジェクトも登録したい」と言われたら、initial-setupを先に済ませてからproject-setupへ進む。
sync-memory
このセッションの会話内容(transcript)を解析し、以下の記録・更新をすべて実行してください。
引数なしなら標準形(下記1〜6)を実行する。--minimal 引数(/sync-memory --minimal など)が渡された場合は最小形を実行する。
このセッションがorchタグの付いたアクティビティ(orch)の担い手で、ユーザーがこの窓口を閉じると言っているなら、以下の手順に入る前にorch skillの「空ける」を先に実行する。閉じないsync-memory(途中の記録など)では空けない。
実行手順(標準形)
1. 未記録区間の特定
まだ記録されていない区間(トピック・決定事項・ログ・資材・アクティビティ)を洗い出す。ここで洗い出した範囲を次のステップでまとめて記録する。同じ突き合わせをステップ4以降でやり直す必要はない。
アクション:
- セッション中に使ったトピックの
get_decisions(entity_type="topic", entity_id=...)とget_logs(entity_type="topic", entity_id=...)を実行し、直近の決定事項・ログを取得 get_activities(status="active")で未完了アクティビティを取得(pending + in_progress)- 取得した既存データとtranscriptを照合し、まだ記録されていない議論・決定・成果物・アクティビティの範囲を特定する
重複防止の判定基準:
- 同じ意味・内容のdecisionが既にあれば記録しない(完全一致でなくても意味が同じならスキップ)
- 同じ意味・内容のlogが既にあれば記録しない
- 同じタイトル・目的のアクティビティが既にあれば記録しない
- 同じテーマのtopicが既にあれば記録しない
2. 未記録区間の記録
ステップ1で特定した範囲を、トピック・資材・決定事項・ログ・関連に振り分けて記録する。
トピックの特定・作成 (add_topic)
transcriptを解析し、議論されたテーマを特定する。
チェック項目:
- 新しい議論テーマが出ていないか?
- 既存トピックの子トピックとして切り出すべきものはないか?
- トピックが広すぎて分割すべきものはないか?
アクション:
- 既存トピックにマッチするものがあればそれを使う
- 新しいテーマがあり、かつ記録(decision/log)が必要な場合のみ
add_topicで作成 - 作成時は
tagsにdomain:タグ(必須)+内容を表すタグを付ける
資材の保存 (add_material)
セッション中に生成・確認された「静的な情報」を資材として保存する。資材はセッション終了とともに揮発するため、ここで永続化する。
materialに入れるもの(静的な情報 = 事実・成果物・スナップショット):
- 分析結果・調査レポート
- 設計ドラフト・仕様案
- 調査で判明した事実(仕様、挙動、制約など)
- コード(生成したコード、差分、設定ファイルの内容など)
- 比較表、一覧表
logとの棲み分け:
- material = それ自体は変化しない、ある時点での情報。要約せずそのまま保存する
- log = 議論の流れ・判断プロセス。material IDを参照して経緯を記録する
アクション:
- セッション中の生データを洗い出し、
add_materialでタグ付きで保存する(タグ必須) - 既存 material(ガイド・設計仕様・一覧表など、更新されうる素材)の内容と矛盾・古い情報がある場合は、
search()で対象 material を特定してからupdate_material(material_id, ...)で更新する relatedで関連するアクティビティやトピックとリレーションを張る- 保存した material ID は決定事項・ログの記録で参照する
決定事項・ログの記録 (add_decision / add_log)
合意が成立した内容(decision)と、議論の経緯(log)を記録する。
決定事項の判定基準:
- ユーザーが「OK」「それでいこう」「了解」「いいね」等で承認した
- AIの提案に対して明示的な同意があった
- 「〜で決定」「〜に決めた」等の表現がある
(正本は decision-record skill の「合意判定基準」節。本ステップの記述と食い違う場合はそちらに従う)
ログの記録対象(議論の流れ・判断プロセス):
- 議論の流れ(ユーザーの発言とAIの応答の要点)
- 検討した選択肢とその比較
- 採用しなかった案とその理由
- なぜその結論に至ったかの経緯
チェック項目:
- 記録漏れの決定事項はないか?
- 各決定事項は適切なトピックに紐づいているか?
- decision と reason が明確に分離されているか?
- 議論の経緯がlogとして残せているか?
アクション:
- 未記録の決定事項があれば
add_decisionで記録 - 議論の経緯があれば
add_logで記録 - log には保存した material ID を参照として含める(例: 「分析結果(material #NNN)を踏まえてA案を採用」)
topic_idは関連するトピックを指定tagsで内容を表すタグを付ける(省略時はtopicのタグを継承)- 記録したdecisionの中に、今後の作業や継続議論を伴うものがあれば、対応するアクティビティを
add_activityで作成する(ステップ3で未登録の場合)
CALM自身の不具合・使用感の違和感・既存記録との矛盾に気づいた場合は
add_logs ではなく report_signal を使う(kind一覧は report_signal ツールの
docstringを正とする)。
reasonの定型節(任意):
議論の中で他案を検討して採らなかった・適用範囲が限定的・実測して確認した、といった
情報があれば、reason本文の末尾に定型節(却下案:/適用条件:/適用外:/検証:/隣接確認:)で書く。
書式の詳細は decision-record skillを参照する。将来のセッションが同じ案を再提案したり
射程外に誤適用したりすることを防ぐ。節はすべて任意で、該当なしなら書かない(空項目・
ダミー項目を作らない)。
add_decisions はこの節をパースして precedent としてレスポンスにechoする。書いたつもりの
節がechoに現れなければ書式ゆれの可能性がある(precedent_warnings を確認する)。
未決定の論点を記録 (add_decision)
議論が途中で終わった論点・アイデア・検討事項を記録する。決定していなくても記録する。
[議論中] の記録基準の正本は decision-record skill の「未決論点の記録: [議論中]」節であり、本ステップの記述と食い違う場合はそちらに従う。[未完] はアクティビティ側の関心事であり、ステップ3で扱う。
記録すべきもの:
- 議論に出たが結論が出ていない論点
- 「〜かも」「〜という案もある」「〜どうしようかな」
- 提案されたが承認/却下がまだのアイデア
- 次のセッションで継続すべき検討事項
チェック項目:
- 議論が途中で終わっている論点はないか?
- 出てきたアイデアが記録されずに消えていないか?
アクション:
add_decisionで記録(決定事項と同じテーブルで管理)- プレフィックスをつける:
[議論中]([未完]はアクティビティのタイトル用で、decisionには付けない) tagsで内容を表すタグを付ける- フォーマット例:
decision: "[議論中] Skillの発動条件をどう改善するか(選択肢: A案, B案, C案)" reason: "議論は出たが結論未定。次セッションで継続" - 論点が大きい場合は子トピックとして切り出す
リレーションの確認・追加 (add_relation)
記録したトピック・アクティビティ間の関連を add_relation で追加する。ここまでトピック・アクティビティの新規作成も既存エンティティへの記録もなかった場合はこの節をスキップする。
判断基準:
- 「この2つは関連している」と思ったら張る(過剰 > 不足)
- 間違ったリレーションは
remove_relationで消せるため、迷ったら張る
チェック項目:
- 同じテーマを扱うtopic同士にリレーションがあるか?
- アクティビティとその背景トピックにリレーションがあるか?
- 関連するアクティビティ同士にリレーションがあるか?
アクション:
add_relation(source_type, source_id, targets=[{"type": "...", "ids": [...]}])で追加- 新規作成した topic / activity だけでなく、既存エンティティとの関連も確認する
3. アクティビティの始末(自セッションが触ったものに限る)
自セッションが触った(言及・着手・作業した)アクティビティに限り、次の3つを行う。全アクティビティを対象にした整理はステップ4a(棚卸し)の役割であり、ここでは扱わない。
未登録の作業を起票する
実装予定・作業予定をすべて登録する。ここで登録したアクティビティは、資材保存の紐づけ先になる。
アクティビティの判定基準:
- 「〜を実装する」「〜を作る」「〜を追加する」
- 「〜が必要」「〜をやる」
- 決定事項から派生する実装作業
チェック項目:
- 記録漏れのアクティビティはないか?
- アクティビティの粒度は適切か?(1つのPRで完結する程度)
- description に十分な情報があるか?
アクション:
- 未登録のアクティビティがあれば
add_activityで登録 tagsにdomain:タグ(必須)+内容を表すタグを付ける- 関連する仕様書があれば description に参照を含める
- 起票するアクティビティについて、transcript中でこの作業の終了条件が明言されている、または推せるなら、起票と同じタイミングで確認なしに
set_goal(activity_id, goal={"new": {...}})をopenの条件として書く。候補が複数で定まらない、またはそもそも推せないときは書かない(事後の一括処理でユーザーに聞く相手がいないため、未定義のまま残す)
確信度「高」を自動クローズする
判定対象は、節見出しのとおり自セッションが触ったアクティビティに限る。以下の基準(フェーズ遷移済み等)はDB状態だけで機械的に真偽が付くが、それでも自セッションが触っていないアクティビティには適用しない。ステップ1で取得した全アクティブアクティビティのうち、自セッションが触っていないものは、基準に該当していてもここでは判定しない(該当すればステップ4aの棚卸しの対象になりうる)。
既存アクティビティの完了状態を以下の確信度で判定する:
- 高(自動クローズ): エージェントが
update_activity(status="completed", closed_by="claude")を実行する。ユーザー確認不要- PRマージ済み(transcript内でマージ確認済み)
- フェーズ遷移済み(後続のdesign/implementアクティビティがin_progress以降)
- セッション内でゴール達成が明確
- ユーザーが満足している様子、または最後のステップがユーザー単独の作業だった
- 例外:
intent:implementのアクティビティで、対応するPRがまだマージされていないものは、上記のいずれに該当してもこのステップでは閉じない
- 中(自動判定): ステップ4aの棚卸しで自動的に処理する
- 前回セッションであと一歩だったもの(残タスクが軽微)
- 外部で完了した可能性が高いもの(transcript外の状況変化を示唆する情報がある)
- 低(自動判定): ステップ4aの棚卸しで自動的に処理する
- 7日以上放置されているもの
- 重複しているもの
- 状況変化で不要になったもの
アクション:
- 確信度「高」のアクティビティは
update_activityでcompletedにする(自動クローズしたものはステップ6で事後報告する)。ただし対象が goal に紐づいている場合はupdate_activityでは completed にせず goal 機構側で扱う(get_goal(activity_id=...)で確認する)。外部の完了(PRのマージ状況など)を根拠にする条件は、ghなど実際の手段で確かめられれば該当条件をupdate_goalでsatisfiedに書き、確かめた事実をadd_materialかadd_logsに残す。確かめられないものは推測のままsatisfiedにしない。確かめた結果で全条件が終端すればjudge_goalも呼んでよい(open_questionsの扱いはcheck-inの「goalフィールドの扱い」節に従う) - 自動クローズしたアクティビティに次フェーズがあれば、アクティビティを作成する(例:
[議論]完了 →[設計]を作成)。既に存在すればスキップ。確信が持てなければ作成せず現状のまま残す
未完の作業を引き継ぐ([未完])
セッション中に途中で終わった話・作業がある場合、次のセッションでこのアクティビティだけ見れば文脈が取れるレベルでアクティビティを登録する。
対象:
- 議論が途中で終わった話題(設計の途中、要件の詰めが途中など)
- 実装に着手したが完了していない作業
- ユーザーから依頼されたが未着手のもの
アクティビティの書き方:
- title:
[未完] 〜のプレフィックスをつける tagsにdomain:タグ(必須)+内容を表すタグを付ける- description に文脈を多めに記載する。具体的には:
- 何について話していたか
- どこまで進んだか・何が決まったか
- 何が残っているか・次に何をすべきか
- 関連するトピック名・決定事項の概要
フォーマット例:
title: "[未完] sync-memoryに未完アクティビティ自動作成機能を追加"
description: "「sync-memory改善」トピックで議論中。決定事項の記録はそのまま残し、追加でadd_activityでも登録する方針で合意済み(decision A案)。残作業:SKILL.mdへのステップ追加と動作確認。"
注意:
- 未決定の論点を記録する節の
[議論中]decision とは別に、アクティビティとしても登録する(役割が異なる:decisionは「何が未決定か」、アクティビティは「次に何をすべきか」) - 未完の話がなければこの節はスキップする
- transcript中でこの作業の終了条件が明言されている、または推せるなら、起票時に上記「未登録の作業を起票する」節の手順で確認なしに
set_goal(new)を書く。候補が複数で定まらない、またはそもそも推せないときは書かない
4. 棚卸し・remember(自動実行)
ステップ4a〜4bの判定に基づき、ユーザーに確認せずClaudeが判断してその場で処理する。ただし4bでrememberの判定が承認を要求する置き場になったものは、承認なしに書ける置き場へ格下げしてその場で書く(下の4b参照)。処理内容はステップ6の完了報告にまとめて記載する。4aが何も無ければ4aは黙ってスキップしてよい。4bは省略せず必ず実行し、結果(訂正の件数)を完了報告に必ず書く。
4a. アクティビティの棚卸し
(本節の判定基準が recompose-context skill の全体モードの「3. 処遇判定」節と食い違う場合は、そちらを正本とする)
goal付きアクティビティの扱い: 以下の判定でcompletedにする(または重複統合で閉じる側にする)前に、対象が goal に紐づいていないか get_goal(activity_id=...) で確認する。goal に紐づいている場合、この棚卸しの推定だけではcompletedにせず、judge_goal も呼ばない(このセッションに根拠のある充足だけが判定材料になり得るが、推定に基づくこのステップの判定はその根拠にならない)。ただし外部の完了を、ステップ3の確信度「高」と同じ基準(gh など実際の手段で確かめられれば update_goal で該当条件を satisfied に書き、終端すれば judge_goal も呼んでよい)で確認できた場合はその限りではない。重複判定(下記1)でも、goal付きのアクティビティは閉じる側にしない(残す側にする。両方がgoal付きなら、このステップでは統合せず現状のまま残す)。
まずスキップ判定: ステップ1で取得したアクティビティを以下のカテゴリに照合し、該当が1件もなければ即座にスキップする。 ユーザーにアクティビティ一覧を見せたり、「該当なし」と報告する必要はない。
判断基準 — いずれかに該当するアクティビティがある場合のみ処理対象とする:
(確信度「高」のアクティビティはステップ3で自動クローズ済みのため、ここでは扱わない)
確信度「中」(完了の可能性が高いがエージェント判断では確定できないもの):
- 前回セッションであと一歩だったもの(残タスクが軽微)
- 外部で完了した可能性が高いもの(transcript外の状況変化を示唆する情報がある)
→
update_activity(status="completed", closed_by="external")で自動的にcompletedにする(ステップ3の確信度「高」と同様の扱い)
確信度「低」(整理・棚卸し対象):
- 重複: 同じ目的・内容のアクティビティが複数存在する場合の片方 →
update_activity(status="completed", closed_by="claude")にする。判定優先順位: まず情報量(description・タグ・関連リレーションの充実度)が少ない方を選ぶ。情報量が同程度の場合のみupdated_atが古い方を選ぶ - 放置:
max(updated_at, last_heartbeat_at)から7日以上経過しているpendingアクティビティ → 前提が変わらずまだ必要と判断すればupdate_activity(activity_id, status="snoozed")で寝かせる(snooze期間経過後に自動でpendingに復活する)、状況を見て不要と判断すればupdate_activity(status="completed", closed_by="claude")にする - 状況変化で不要: 前提条件が変わり、もうやる意味がないアクティビティ →
update_activity(status="completed", closed_by="claude")にする。description先頭に理由を追記する(例: 「YYYY-MM-DD sync-memoryで前提変更によりcompleted」) - フェーズ移行済み: in_progressの議論アクティビティ(intent:discuss)で、後続フェーズが既に動いているもの。以下のいずれかで検出する:
- depends_onで下流アクティビティ(intent:design/implement)がin_progress以降
- 同トピック内でintent:discussがin_progressかつ、intent:design/implementのアクティビティが存在する
→
update_activity(status="completed", closed_by="claude")にする
いずれも判断に迷う場合は、より安全な側(消さない・completedにしない、現状のまま残す)に倒す。
4b. 記憶すべき知見の判定(remember)
セッションのtranscriptを振り返り、記憶すべき知見を収集・判定する。最初に人間の訂正を拾う。 他の収集パターンはその後にする。
手順(この順で行う):
- 訂正を拾う: transcript中の人間の発話から、Claudeの言動を誤りとして直したもの(「〜じゃなくて」「〜しないで」「〜のほうがいい」「なんで〜したの」、同じ指摘の繰り返し)を全部リストにする。1件ずつ、何を直されたかを1行にする。0件なら0件と数える(SAの報告・他セッションのメッセージ・システム通知は含めない)
- 既存の教訓の索引を1回で引く:
get_feedback_entries()を1回呼ぶ(50件以下なら引数なしで全件、超えるなら訂正の語で絞り、絞ったときは完了報告の注意事項にそう書く)。文脈内のauto-memory索引・habits/rules・触れたタグのtag-notesも合わせて見る。リストの訂正をこの索引とまとめて突き合わせ、各訂正を「新規」か「再発(既存の教訓名)」に振り分ける。訂正ごとのCALM searchは回さない(判例decisionの要否判定が要るネタだけ、rememberの手順でsearchする) - 書く: 1件ずつ remember skillの判定フロー(前処理3のうちフィードバックエントリ・文脈内索引の確認は2で済んだものとして扱う)に従って置き場を決め、書く。再発はrememberの「再発の手順」でstumbleを書く
- 訂正以外の収集パターンも拾う: エージェントのやらかし(コマンドミス、間違った前提での行動)、ハマりポイント、ユーザーの非自明な肯定、新発見(調査で判明した仕様・制約)。これらも3と同じく1件ずつremember経由で置き場を決める
置き場の決め方と書き込みの注意(承認の要る置き場の格下げ、tag notesの全文置換への注意など)はremember側の手順に従う。ただしsync-memoryは事後の一括処理でユーザーに聞く相手がいないため、次のとおり読み替える。
- 確認の規定で「承認を得てから書く」置き場(rules・habits・CLAUDE.md・判例decision・新しいdecision)になったネタは、承認不要の置き場のうち最も強いところへ格下げして、その場で書く。字面で照合できるもの(人間の発話・ツール失敗・実行直前の引数)はフィードバックエントリ、照合できないものはauto-memoryに書く。本来の置き場の候補は残す(エントリならrefに「本来の置き場の候補: habits」のように、auto-memoryなら本文に書く)
- 「書いたあと報告」の置き場は、その場で書き、報告はステップ6の完了報告に含める(個別の1行報告はしない)
- 「ユーザーに確認する」「判定に迷う」「rule-placementのfull評価でも決めきれない」ネタは書き込まない。完了報告の注意事項に、迷った点とともに記す(誤って書くより書かないほうが安全)
- rememberの発動契機のうち、ユーザーへの応答として先に直す手順(訂正なら先に直す)は、すでに済んだものとして扱う
- 再発として既存の記録に追記する場合は、追記(stumbleまたは再発の行)を書いたうえで、強い置き場への格上げが必要になったときはrememberの「格上げの承認の取り方」の人がいない場面に従い、メタaskを起票する
訂正が0件で、他にも記録すべきものがなければ、書き込みなしで終える(完了報告には「訂正: 0件」の行を書く)。
5. 聞き返しの後追い検出(条件付き)
セッション中にClaudeがユーザーへ聞き返した質問(AskUserQuestion)と、「これ前に決めなかったっけ」のような過去の議論を指す定型の発話を機械抽出し、既存記録との類似照合を経て「既存記録で答えられたはずだったか」を判定する。yesと判定した候補は report_signal(kind="precedent_miss") で計測台帳に積む。
注意: 抽出が拾うのはAskUserQuestionの呼び出しと数個の固定フレーズだけである。「〜しないで」のような通常の訂正は拾わない(それは4bの担当)。実績では抽出が0件のことが大半で、0件でも異常ではない。
前提スキップ: 候補が0件のときはこのステップ全体をサイレントスキップする。ユーザーへ「該当なし」と報告する必要はない。
手順:
- SessionStart時にコンテキストへ注入された「このセッションのtranscript path: ...」の行からtranscript pathを取り出す。無ければこのステップをスキップし、完了報告に一行残す
- 取り出したtranscript pathを渡して
detect_reask_candidates(transcript_path=<path>)を1回呼ぶ。旧来の抽出スクリプト(scripts/detect_reask_candidates.py相当)・excluded_reasonが付いた候補の除外・残候補のうち先頭N件(上限あり。Nを超える候補は判定対象外とし、超過した旨を完了報告に一行残す)へのsearchバッチ実行までを内部で行い、各候補に既存記録top-3(top_hits。閾値は本ステップ末尾の実装ノート参照)が付いたcandidatesを返す - 個別の
search呼び出しは発生しない(手順2に集約済み) - 候補ごとの
candidate.degraded(内部で行われたsearchバッチ呼び出しのdegradedを候補単位に反映したもの)でdegraded=trueのときは判定を保守側に倒す(該当候補についてはprecedent_miss記録を行わない。skipした事実は完了報告に一行残す) - 候補ごとの
top_hits(閾値は本ステップ末尾の実装ノート参照。detect_reask_candidatesが内部で閾値判定済み)を「高類似ヒット」として扱う。高類似ヒットが1件もない候補は判定・記録の対象外とする。高類似ヒットがある候補についてのみ、Claudeが「この既存記録があれば、この聞き返しはそもそも不要だったか」を判定する。この判定はClaudeの主観判断であり、同じ候補・同じ既存記録でも判定がぶれうる - yes判定のみ
report_signal(kind="precedent_miss", summary=..., detail=..., refs=[高類似ヒットの各id], context={"missed_ids": [...]})を呼ぶ。summaryのフォーマットは下記参照(dedup fingerprintの安定性のため決定論的な文字列に固定する) - 判定ログ(候補text・ヒットid・判定結果)は本ステップ内では保存しない(signal_events側のcontextに集約される)
記録で答えられない性質の候補は除外する:
- Claudeの意見・選好を求める質問(「A案とB案どっちがいい?」等)
- ユーザー自身の選好・状況を尋ねる質問(「今日どこまでやりたい?」等)
- セッション外の環境事実(OS状態・CI状態・PR状態など、記録に載せる対象ではないもの)
report_signalのsummaryフォーマット:
summaryは決定論的な文字列 missed: <最上位ヒットの既存記録type>#<id> に固定する(自由記述の要約はdetailに書く)。高類似ヒットが複数件ある場合は、refsのうち最もscoreが高いものを代表として使う。summaryはfingerprint計算にそのまま使われるため、自由記述にすると同じ既存記録を別セッションで踏み直したときに文言が実行ごとに揺れ、fingerprintが一致せずdedupが発火しない。
実装ノート(初期値、観察後に確定値へ差し替え):
- 判定に回す候補上限N: 5〜10件(
detect_reask_candidatesのsearch_top_n引数、既定8件) - 「高類似ヒット」の閾値: search score 0.4以上(
detect_reask_candidatesのscore_threshold引数、既定0.4) - 除外辞書:
scripts/detect_reask_candidates.pyの組み込み既定を使う(detect_reask_candidatesツールは辞書差し替え引数を持たない。差し替えが要る場合は従来通りスクリプトを直接呼ぶ)
6. 完了報告とふりかえり
以下の形式でサマリーを報告する。件数カウントは不要。記録した内容の概要を箇条書きで列挙する。 該当がないセクションは省略する(ただし「記憶」の訂正の行は0件でも書く)。
## sync-memory 完了
### トピック
- (作成したトピック名を列挙)
### アクティビティ
- (登録・完了にしたアクティビティを列挙)
- (ステップ3で確信度「高」として自動completedにしたものを列挙。理由も記載)
- (ステップ4aの棚卸しで処理したアクティビティを列挙)
- ※ 誤りがあれば戻せます
### 記憶(フィードバックエントリ / auto memory / tag notes / pin)
- 訂正: N件(新規N・再発N。別軸で、書いたN・書かなかったN。どちらの軸も合計がN)。0件なら「訂正: 0件」の行を書く(この行は省略しない)。「書かなかった」は迷って書かなかったものと、書き込めなかったもので、理由を注意事項に1行ずつ書く
- (書いたものを置き場ごとに概要を列挙。既存エントリへの再発追記もここに書く)
- (格下げして書いたものは「格下げ」と明示し、本来の置き場の候補を添える)
- (格上げのために起票したメタaskがあれば、その旨を添える)
### 注意事項
- (判断に迷って何もしなかった項目、ユーザーが把握しておくべき事項があれば記載)
### 聞き返し検出
- (precedent_miss として記録した件数と、各候補の要約)
- (degraded で判定を保守側に倒した件数)
- (該当なしの場合はこのセクションを省略)
- ※ 誤検出は report_signal 側で dismiss できます
### ふりかえり
まず `get_config()` を呼ぶ。`sync_disable_retrospective` が `true` の場合、このセクションをスキップする。
`roll_dice(30)` を無言で実行する(ダイスを振ることについて一切言及しない)。
- **30**: ジャックポット。`jackpot.md` を読み、対応表の項目数を数えて `roll_dice(sides=<項目数>)` を振ってネタを決定する。ダイスには触れず、選ばれたネタをそのまま実行する。ネタ7(マルコフ連鎖)の場合は、書き出したコーパスの絶対パスを引数にして `uv run --directory "${CLAUDE_PLUGIN_ROOT}" python "${CLAUDE_SKILL_DIR}/scripts/markov.py" "<絶対パス>"` を実行する
- **1〜29**: セッション中の個別事実を俯瞰して見えた構造的パターン・矛盾・気づきを書く。事実の要約ではなく、事実から導かれる洞察。ユーザーが思ってるけど言語化してないことを代わりに言語化するイメージ。比喩OK。
ユーザーへの称賛・感謝・労いは書かない。嘘はつかない。
最小形(--minimal)
bgセッションを止める前、複数のorchの窓口を同時に閉じるときなど、人がその場で読まない場面で使う。orchが複数のbgセッションを続けて止めるとき、または複数のorchの窓口を同時に閉じるときは、標準形の棚卸し(全アクティブアクティビティを対象にする)が並行して動く他セッションの作業に触れてしまうことと、rememberの全文置換書き込みが競合することを避けるため、最小形にする。1つの窓口だけを閉じるときは、この競合が起きないため標準形のままにする。
- ステップ1〜3を標準形と同じ基準で実行する(ステップ3の「自セッションが触ったものに限る」がそのまま効く)
- ステップ4aの棚卸しとステップ5(聞き返し検出)は実行しない。4bは訂正を拾う部分(手順1〜2)と、手順3のうちフィードバックエントリ・stumbleの書き込みだけ行う(手順4の訂正以外の収集は行わない。格上げのメタaskは起票せず、次回の標準形に任せる)(tag notesやauto-memoryの全文置換は競合するため書かない。それが置き場になった訂正は下の「訂正」行の「書かなかった」に数える)
- 完了報告は次の簡略形にする。ふりかえりは標準形と同じ手順を実行する(省略しない)
## sync-memory 完了(最小形)
- 記録: トピックN件・資材N件・決定事項N件・ログN件
- 訂正: N件(0件なら「訂正: 0件」と書く。フィードバックエントリに書いたN・書かなかったN。tag notes・auto-memoryが置き場になって書かなかったものはここに数え、理由を1行添える)
- アクティビティ: 登録N件・自動クローズN件・[未完]引き継ぎN件
### ふりかえり
まず `get_config()` を呼ぶ。`sync_disable_retrospective` が `true` の場合、このセクションをスキップする。
`roll_dice(30)` を無言で実行する(ダイスを振ることについて一切言及しない)。
- **30**: ジャックポット。`jackpot.md` を読み、対応表の項目数を数えて `roll_dice(sides=<項目数>)` を振ってネタを決定する。ダイスには触れず、選ばれたネタをそのまま実行する。ネタ7(マルコフ連鎖)の場合は、書き出したコーパスの絶対パスを引数にして `uv run --directory "${CLAUDE_PLUGIN_ROOT}" python "${CLAUDE_SKILL_DIR}/scripts/markov.py" "<絶対パス>"` を実行する
- **1〜29**: セッション中の個別事実を俯瞰して見えた構造的パターン・矛盾・気づきを書く。事実の要約ではなく、事実から導かれる洞察。比喩OK。
ユーザーへの称賛・感謝・労いは書かない。嘘はつかない。
注意
- 未決定の論点は add_decision で記録する - プレフィックス
[議論中]をつけて区別([未完]はアクティビティのタイトル用) - 判断に迷う場合は、記録する方向で進める(後で修正可能)
- 既に記録済みのものは重複して記録しない - ステップ1で取得した既存データと照合すること
- 現在進行中の作業がある場合は
add_activityで登録し、update_activityでin_progressにする - ステップ1〜5(棚卸し・rememberを含む)ではツール呼び出しの前後に判断理由・中間分析・進捗報告のテキストを出力しない。見せるのはステップ6の完了報告のみ(最小形も同様、簡略形の完了報告のみ)
- 個別の経緯・成果物のその場記録はrecording skillの担当
tag-cleanup
analyze_tags でタグの共起分析を実行し、整理提案をユーザーに提示する。ユーザーが承認したアクションのみ実行する。
関連skillとの境界
- 「タグが散らかってきた」のような、タグ全体の整理の依頼で使う
- 個別タグのnotes編集(tag-notes)では発動しない
手順
- 引数で
domainが指定されていればそのまま使う。指定されていなければ、どのドメインで分析するか(または全体か)をユーザーに確認してからanalyze_tags()を呼ぶ - 結果を以下の5セクション構成でユーザーに提示する
- ユーザーが承認したアクションを
update_tag/demote_tag_notesで実行する - 実行結果を
add_materialで保存する
提示フォーマット
分析結果を以下の順序で提示する。該当がないセクションは省略する。タグ名のみで提示し、内部IDは表示しない。
1. 重複候補(suspected_duplicates)
名前が類似しているタグのグループ。rename または canonical 化を提案する。
## 重複候補
| グループ | タグ | 提案 |
|---------|------|------|
| 1 | `checkin`, `check-in`, `activity-checkin` | `check-in` に統一(他を canonical 化) |
提案の方針:
- usage が最も多いタグ、または最も一般的な命名規則に合致するタグを正規名にする
- 残りは canonical 化(エイリアスとして維持)または rename(完全置換)を提案
2. クラスタ(clusters)
自然にまとまるタグ群。まとめタグの新設や既存タグへの集約を提案する。
## クラスタ
| # | タグ群 | cohesion | 提案 |
|---|--------|----------|------|
| 1 | `stop-hook`, `hook-system`, `pretooluse`, `event-driven` | 0.85 | まとめタグ不要(既に `hook-system` がある) |
提案の方針:
- まとめタグがすでに存在する場合はその旨を記載
- 存在しない場合は「
xxxタグの新設を検討?」と提案
3. 孤児タグ(orphans)
usage が低く、吸収先がありそうなタグ。canonical 化を提案する。
## 孤児タグ
| タグ | usage | 最寄り | PMI | 提案 |
|------|-------|--------|-----|------|
| `hook_state` | 1 | `hook-system` | 2.1 | `hook-system` に canonical 化 |
提案の方針:
- nearest と PMI を参考に吸収先があれば canonical 化を提案する
- 吸収先が無い(nearest が null)、または統合ではなくタグ自体を使わなくする場合は archived 化(退役)を提案する。archived は物理削除ではなく
archived=Falseでいつでも解除できるため、判断に迷う孤児タグはまず archived を優先する
4. 共起情報(co_occurrences)
タグ間の関係の強さ。参考情報として提示するのみで、直接のアクション提案はしない。
## 共起情報(参考)
| タグA | タグB | PMI | 共起数 |
|-------|-------|-----|--------|
| `stop-hook` | `hook-system` | 3.2 | 30 |
5. 予算超過タグ(notes_over_budget)
notesが天井(4,000字)を超えているタグ。analyze_tagsはdomain等の分析スコープに関わらずnotesを持つ全タグを対象に走査するため、domain指定時も漏れなく提示する。
## 予算超過タグ
| タグ | 現在の字数 | 天井 |
|------|-----------|------|
| `domain:calm` | 5,120 | 4,000 |
提案の方針:
- 原則
demote_tag_notes(tag=..., sections=["見出しテキスト", ...])でセクション単位に資材へ退避することを提案する(sectionsはnotes中の##見出しで指定、状態・進行ジャーナル型のセクションはmode="drop"、それ以外は既定のmode="pointer") - タグ自体を今後使わない場合のみ archived 化を提案する(archived 化は超過の解消手段ではなく、タグそのものを退役させる別処置)
- 終了条件はdemoteの実行回数ではなく、返り値の
notes_length.over_budgetがfalseになったことで判定する
アクション実行
ユーザーが承認したアクションのみ実行する。自動実行はしない。
- canonical 化:
update_tag(tag="旧タグ", canonical="正規タグ") - rename:
update_tag(tag="旧タグ", rename="新タグ") - archived 化(退役):
update_tag(tag="対象タグ", archived=True, archived_reason="理由")。他タグの canonical 先になっているタグは archived 化できない(先にエイリアス解除が必要) - notes縮小:
demote_tag_notes(tag="対象タグ", sections=["見出しテキスト", ...])で該当セクションを資材へ退避(承認された見出しのみ対象にする) - 実行後、変更内容を一覧で報告する
結果の保存
実行したアクションの一覧を add_material でタグ付きで保存する。タイトルは「タグ整理結果 YYYY-MM-DD」とする。内容には実行したアクションと変更前後の状態を含める。タグには domain: タグと tag-cleanup を付ける。
MCP servers 1
Sponsors
Details
- Marketplace
- isizono/cc-memory
- Category
- Community