今すぐ実行
対象: $ARGUMENTS
KB内のすべてのドキュメントはコレクション内に存在します。コレクションとは、kb/notes/、kb/reference/、kb/instructions/、またはインストールされたライブラリコレクション（例: kb/commonplace/notes/）のように、kb/ 以下のディレクトリにローカルの COLLECTION.md が置かれたディレクトリのことです。書き込みを受け付ける各コレクションには、その登録簿、品質目標、型の提供、リンク規則を記載した COLLECTION.md があります。
フロントマターを持つドキュメントは、パス値の type: を持ちます（例: type: kb/types/note.md または type: kb/reference/types/adr.md）。フロントマターのないファイルは暗黙的に text として扱われます。
ステップ1 — 引数を解析する
編集モード: 最初の引数は既存の .md ファイルへのパスです。それを読み込み、パスからコレクションを推測し、フロントマターから type: パスを読み取ります。フロントマターはあるが type: がない場合は、編集前にその構造的問題を修正してから停止します。フロントマターがない場合は、暗黙的に text として扱います。構造編集を行う前に、type: で指定された型仕様ドキュメントを開きます。
新規作成モード: 上記以外のすべてのケースです。引数からコレクション、型、トピックを抽出します。デフォルト: コレクション notes、型 kb/types/note.md。要求された型が指示（instruction）で、コレクションが明示されていない場合は、コレクション instructions を使用します。
新規作成の場合、対象コレクションを kb/ 以下の、ローカルの COLLECTION.md を持つディレクトリに解決します。省略名（例: notes）は kb/notes/ を意味します。そのコレクションの ## Types セクションを読み、リストされている型パスの1つを選択します。要求された型がリストされておらず、ユーザーが明示的なパスを指定しなかった場合は、利用可能な型をリストして停止します。ユーザーが明示的な kb/.../*.md 型パスを指定した場合は、そのファイルを開き、それが型仕様ドキュメントであることを確認してから使用します。
ステップ2 — コレクション規則を読み込む
対象コレクションの COLLECTION.md を読み、そのコレクションのライティング規則（外部リンク規則を含む）を取得します。外部リンクに関するセクションを探します（見出しは様々です — 宛先とラベルを指定しているセクションを探します）。それを権威あるものとして扱います。このセクションは、ソースがリンク可能な宛先コレクション、除外される宛先、ソース→宛先のペアごとに許可されるラベル、各ラベルが提供する読者のニーズを示しています。内部形式は様々です（宛先ごとのブロック、宛先列を持つ単一のラベルテーブル、散文） — 形式ではなく内容を読み取ります。参照すべき別個のリンクドキュメントはありません。
ハードフェイル: 対象コレクションに COLLECTION.md がない場合。書き込みを受け付けるすべてのコレクションには COLLECTION.md が必要です。その登録簿、品質目標、リンク規則がコレクションを区別するものです。デフォルトの規則で進めないでください。
ステップ3 — 型仕様を読み込む
選択した型仕様ドキュメントを読みます。そのフロントマターには、type: kb/types/type-spec.md、name、description、schema が含まれている必要があります。本文はアーティファクトの形状を提供し、テンプレートブロックを含む場合もあります。その本文を構造的なオーサリング契約として厳守してください。
型パスがない場合に note にフォールバックしないでください。
text については、ユーザーが明示的に非構造化キャプチャを希望する場合のみ、フロントマターなしの生の Markdown を書いてください。それ以外の場合は kb/types/note.md を使用します。
ステップ4 — 書く前に検索する
書き込みは能動的な発見を実行しません — それは cp-skill-connect の役割です。書き込みは1つのノートを作成し、執筆者がすでに手元に持っているリンクと、安価な重複ガードのみをコミットします:
- 重複チェック.
rgを使用して、新しいノートの特徴的なタイトル用語で対象コレクションを検索します（例:rg -i "キーワード" kb/notes/ --glob "*.md"）。これはターゲットを絞った用語検索です — コレクション全体を列挙しないでください。完全なリストはリニアなコンテキストを消費し、単一のノートの重複チェックには不適切なツールです。ほぼ重複が既に存在する場合は、新しいノートを作成するよりも編集する方を優先します。 - 既に読み込まれたコンテキスト. この書き込みのためにセッションに取り込まれたノート、ソース、インジェストは、最優先のリンク候補です。読む価値があったものは、リンクを検討する価値があります。
- ユーザーが指定したターゲット. ユーザーがプロンプトで言及したリンクターゲット。
編集モードでは、対象ノートのバックリンク検索も実行します — 1回のクエリ、本文検索なし — 編集によって依存関係が孤立しないようにします。
これ以上の発見（コレクション全体の説明スキャン、クロスデスティネーションの探索、本文検索、タグトラバーサル、リンクフォロー、逆エッジの推論）はすべて cp-skill-connect に属し、ここでは行いません。書き込みは1つのノートのオーサリングに集中します。
ステップ5 — 草稿を作成して保存する
型仕様ドキュメントとコレクション規則に従います。既存のファイルを編集する場合を除き、# Title から小文字ハイフン形式のファイル名を生成します。型付きアーティファクトの場合、type: には型名ではなく、リポジトリ相対の正確な型仕様パスを設定します。
特性（traits）は明らかに適切な場合にのみ設定します。利用可能な特性とその意味は、対象の型の仕様（例: kb/types/note.md の特性テーブル）で定義されています — 記憶したリストではなく、そこから語彙を取得します。
編集時は、要求された変更でそれらを変更する必要がない限り、既存のフロントマターとリンクを維持します。
ステップ6 — 検証する
作成または編集したノートを検証します:
commonplace-validate path/to/file.md
構造上の失敗を修正してから停止します。
その後、次のステップとして cp-skill-connect を提案します。ステップ4では、執筆者がすでに手元に持っていたリンク（読み込まれたコンテキスト、ユーザー指定）と重複ガードのみがコミットされます。グラフの残りの部分（コレクション全体の説明スキャン、クロスデスティネーション候補、本文検索結果、タグトラバーサル、リンクフォロー、逆エッジ候補）は、コネクトスキルでのみ明らかになります。この提案は省略可能な装飾ではありません。
普遍的なメカニズム
以下は、コレクションに関係なく、すべての型付きアーティファクトに適用されます。
フロントマター によりノートが検索可能になります。フロントマターがない場合は暗黙的な text を意味します。フロントマターがあるファイルには、パス値の type: が含まれている必要があります。ほとんどのライブラリノートには、description（二重引用符で囲み、50〜200文字）と、オプションで traits、tags、status も必要です。
説明文 は要約ではなく、検索フィルターです。テスト: エージェントがこのノートの概念を検索して5件の結果を得た場合、この説明文はその中からこのノートを選ぶのに役立ちますか？ タイトルを言い換えても検索価値はゼロです。
語彙. ルートディレクトリの AGENTS.md で宣言されているアクティブ語彙を使用します。散文を書くか実質的に編集する場合、読者がその用語を知らない可能性がある最初の意味のある言及で、アクティブ語彙を注釈付けしてリンクします。語彙リンクを追加するためだけに、触れていない箇所を変更しないでください。
リンク. ソースファイルからの相対 Markdown パスを使用します。すべてのリンクは実在のファイルを指している必要があります。
位置はコミットメントをエンコードします。インラインの散文接続詞（since [X](./x.md)、because [X](./x.md)、but [X](./x.md)）が最も強力です — ターゲットは現在の議論の前提です。フッターリンクには、明示的なラベルとコンテキストフレーズが含まれます: - [title](./path.md) — label: コンテキストフレーズ。
コレクションの COLLECTION.md は、宛先ごとにラベルを許可し、各ラベルが提供する読者のニーズを指定しています。リンクの目的に合った読者のニーズに対応するラベルを選択し、コンテキストフレーズは「[ソース] は [特定の理由] により [ターゲット] に接続する」という問いに答えるように書きます。許可されたラベルが適合しない場合、その候補はこのコレクションのスコープ外です — リンクをドロップするか、許可を拡張するためにコレクションの作成者にエスカレーションします。
ファイル名 は小文字、ハイフン区切り、.md、# Title から派生、最大70文字です。
蒸留追跡: ノートから焦点を絞ったアーティファクトに蒸留する場合、各ソースノートのフッターに Distilled into: を追加します。蒸留されたアーティファクトはリンクを返しません。
リネーム: 手動でリネームしないでください。commonplace-relocate-note を使用してバックリンクを更新します。