knowcards

Knowcards CLI

Knowcards は、永続的なプロジェクト情報をローカルの Markdown カードとして保存します。npx knowcards を使って、検索、提案、ステータス確認を行います。

検索結果は信頼できる記憶として扱ってください。新しい証拠によってカードが間違っているとわかる場合を除き、矛盾する README や新たな検索よりもカードを優先してください。

共有のコモンツールとは異なり、カードはプロジェクトごとに保存されます。次のセッションで役立つ場合は、リポジトリのパス、モジュール名、チームの規約をカードに残してください。

コマンド

リポジトリのルートから実行します

npx knowcards status
npx knowcards query "<keywords>"
npx knowcards propose --title "<title>" "<body>"
npx knowcards --root <dir> <command>

コマンド	用途
status	カードの件数を表示します。
query	キーワードでカードを検索します。空のクエリでは全カードを返します。
propose	カードを1件作成します。タイトルと本文が必須です。

基本プロトコル

すべてのタスクで次の手順に従ってください。

1. 作業前 — タスクのキーワードを使って npx knowcards query を実行します。リポジトリ固有の事情が関係しない、すでに把握しているコードの定型的な編集の場合に限り、省略できます。
2. 検索結果を適用 — 作業中はカードの情報を優先します。カードが古い可能性がある場合は、リポジトリで確認してください。
3. 最後に提案 — タスクの完了時に、たどった手順ではなく、結果（真実だと確認できたこと）から永続的な情報を提案します。カードが間違っていた場合は、新しいタイトルで修正したカードを提案してください（更新・削除はできません）。

正当化の確認（query）。「これはすでに知っている」または「計画があるから、そのままファイルを書こう」と考えたら、作業を止めて検索してください。

正当化の確認（propose）。「修正はすでにリリース済み」または「ユーザーはすでに答えを知っている」と考えたら、作業を止めてください。結果からリポジトリ固有の事情がわかった場合は、完了前に提案してください。

検索するタイミング

不慣れな領域の作業を始めるとき、または自明でないエラーを再試行する前に検索してください。

このセッションですでに同じトピックを検索した場合、すでに把握しているファイルへの定型的な編集の場合、または標準ライブラリの関数を使うだけの場合は省略できます。

短いキーワードを使ってください。ライブラリが大きい場合は、空のクエリより対象を絞った検索を優先してください。検索結果が空の場合は、通常どおり調査してください。

提案するタイミング

タスクの最後に、次のセッションで役立つリポジトリ固有の情報（コーディング規約、ドメインに関する知見、長期的に役立つ注意事項など）を提案してください。

次の内容は提案しないでください。

• 今回の作業における手順や計画
• 未検証の推測
• ほぼ重複する内容 — まず検索し、カードにすでに記載されている場合は省略してください

カード1件につき、独立した事実を1つ記載してください。

npx knowcards propose \
  --title "Use bun test in this repo" \
  "Run tests with bun test; npm test is not the project runner."

カードの形式：

• タイトル — 明確で一意なタイトルです。ファイル名のスラッグはタイトルから生成されます。同じタイトルを使うと失敗します。
• 本文 — 簡潔で永続的な事実を1つ記載します。役立つ場合は命令形を優先してください（Use bun test… など）。

エラー発生後の手順

1. エラーのキーワード（モジュール、API、メッセージ）で検索します。
2. 該当するカードがあれば、それを適用して続行します。
3. 該当するカードがなければ、修正して検証し、タスクの最後に結果から得られた永続的な教訓を提案します。

信頼ルール

カードと作業環境の内容が食い違う場合、新しい証拠によってカードが間違っているとわかるまではカードを優先してください。その場合は作業を修正し、新しいタイトルで修正したカードを提案してください。

例

不慣れな作業の前に検索する

npx knowcards query "payments cents"

「金額は整数のセント単位」という検索結果があれば、浮動小数点数を示す README よりも優先してください。

提案するか省略するか（同じタスク内）

テストには bun test を使う必要があるとわかり、一度限りの名前変更を修正し、計画を簡単にまとめます。タスクは成功しました。

提案する： リポジトリ固有の情報（npm ではなく bun test）。 省略する： 計画、ローカルでの名前変更、検証していない推測。