project-knowledge-harness

project-knowledge-harness

あらゆるソフトウェアプロジェクトで使える、軽量なファイルベースのメモリーハーネスです。

時間の方向とアクセスパターンで明確に分けた、3つの領域があります。

領域	時間	答える質問	アクセスパターン
TODO.md	未来	「後で何をするか？」	上から順に読む（優先度レーン）
backlog/<slug>.md	未来	「このアイデアの分析内容は？」	TODO.md からインデックス
pitfalls/<slug>.md	過去	「エラー X が発生しました。以前にもありましたか？」	症状を表すキーワードで grep

すでにエージェント契約があるプロジェクトでは、AGENTS.md のハード不変条件が「エージェントが必ず守るべきルールは何ですか？」に答えます。深刻な落とし穴は、ハード不変条件へと昇格します。詳しくは references/when-to-add-docs.mdを参照してください。

このスキルを使うタイミング

ユーザーが次のいずれかを示した場合に、このスキルを使ってください。

• 保存場所のない長期的な TODO リスト、または整理が必要な乱雑な TODO.md（兆候：「アイデアはどこに置けばいい？」「いつかやる」「工程量太大需要再評估」）
• 保存する価値のあるデバッグセッション（兆候：「同じ問題を何度も解決している」「このトラブルシューティングを保存して」「踩過的坑」「TROUBLESHOOTING.md が docs/ 内に散らばっている」）
• IDEAS.md／ROADMAP.md／WISHLIST.md／LESSONS.md ファイルを統合する依頼

アクティブなスプリント計画には、このスキルを使わないでください（課題トラッカーを使います）。一時的なエージェント用スクラッチパッドにも使わないでください（.claude/plans/ を使います）。現在の機能に関するドキュメントにも使わないでください（docs/ を使います）。

このスキルの適用方法（デフォルトのワークフロー）

このスキルには、5つのスクリプトと複数のテンプレートが含まれています。セットアップではデフォルトで初期化スクリプトを使ってください。また、情報の記録には、エージェントに TODO.md を手作業で編集させるのではなく、デフォルトで add-todo.sh／sweep-inbox.sh を使ってください。

scripts/
  init.sh         # one-shot setup of TODO.md + backlog/ + pitfalls/
                  # + agent guidance + README snippet
  todo-kanban.sh  # validate TODO.md format and render kanban-style board
  add-todo.sh     # insert a structured entry into the right ## P* lane
  promote-todo.sh # move an active TODO item to ## Done with the right syntax
  sweep-inbox.sh  # triage backlog/inbox.md into TODO.md via add-todo.sh

1. 対象リポジトリに対して scripts/init.sh を実行する

scripts/init.sh \
  --target /path/to/project \
  --project-name "My Project" \
  --deployment chezmoi   # or npm | pip | docker | none

スクリプトの処理内容：

1. assets/*.template からプレースホルダーを置換して、TODO.md、backlog/README.md、pitfalls/README.md を作成します。
2. AGENTS.md／CLAUDE.md にエージェント向けガイダンスを追記します（自動検出。--agent-contract で変更できます）。
3. README.md に「ロードマップと学び」セクションを追記します。
4. scripts/todo-kanban.sh --validate-only TODO.md を実行して、ずれをすぐに検出します。
5. 手動で追加するデプロイ除外の行を表示します（ignore ファイルは編集しません。詳しくは references/deployment-exclusion.mdを参照してください）。

init.sh は冪等です。既存ファイルは --force を指定しない限りスキップされ、スニペットはセンチネルマーカーがない場合にのみ追記されます。

2. 会話の途中で、ユーザーが「いつかやる」アイデアを示した場合

兆候：「いつかやる」「あると便利」「興味があれば」「工程量太大需要再評估」「先記下來」「今ではないけれど……」。

1. まだ TODO.md がない場合は、先に scripts/init.sh を実行します。

2. デフォルトの方法 — scripts/add-todo.sh を呼び出す：優先度、作業量、タイトル、説明を指定します。これにより、該当する ## P* レーンに正式な形式の行が挿入され、再検証されます。会話で十分な調査が行われ、backlog/<slug>.md ドキュメントのひな形を作る価値がある場合は、--backlog を追加します。

   scripts/add-todo.sh --priority "P?" --effort M \
     --title "Try Rspress for docs" \
     --description "Evaluate AI-native docs framework alternative"
   

3. クイック記録の方法 — 優先度や作業量がまだ決まっていない場合や、考えをまとめている途中の場合は、backlog/inbox.md に追記します。

   echo "- $UNSTRUCTURED_THOUGHT" >> backlog/inbox.md
   

   後で（このセッション中、または次回）scripts/sweep-inbox.sh を実行して、未整理の行を1つずつ正式な形式にし、TODO.md に追加します。このスクリプトは、各行の不足項目を尋ねます。--batch モードでは、priority=… effort=… title="…" description="…" の組がすでにある行だけを処理し、判断が必要な行はそのまま残します。

4. 手動編集の方法 — スクリプトで対応できない場合に限ります。 references/tag-schema.mdの構文を使い、編集後に scripts/todo-kanban.sh --validate-only を実行します。

5. --backlog を使うか手作業で backlog/<slug>.md を作成した場合は、インデックスからドキュメントを参照できるよう、TODO の行末が → [research](backlog/<slug>.md) になっていることを確認してください。

3. 会話の途中で、難しい問題のデバッグが終わったとき

兆候：「ふう、時間がかかった」「妙ですね。エラーには X について何も書かれていませんでした」「これに遭遇したのは今回で 3 回目です」といった発言がある場合や、どのドキュメントにもないコンテキストを自分で再構成していることに気づいた場合です。

1. 痕跡が新しいうちに、assets/pitfall-doc.md.template から pitfalls/<symptom-slug>.md をすぐに作成します。ドキュメントのタイトルには根本原因ではなく症状を使います。最終的にわかった原因ではなく、目にしている現象で検索するためです。
2. エラーメッセージは一字一句そのままコピーします。言い換えると grep で検索できなくなります。
3. 罠が深刻な場合（気づかないまま発生する破損／複数のマシンで再発／わかりにくい回避策）は、表面化させます。「これを AGENTS.md の厳格な不変条件に昇格させるべきか？」と検討してください。references/when-to-add-docs.md を参照してください。

4. TODO.md の項目を実装したとき

同じコミットで、次を行います。

1. scripts/promote-todo.sh --title "<substring>" --summary "<what shipped>" を実行します。アクティブな行を削除し、日付入りの Done エントリーを挿入してから、再検証します。部分文字列に一致するアクティブな項目が 0 件、または複数件ある場合は実行を拒否します。
2. backlog/<slug>.md が存在する場合は、Status: shipped に設定します（隣接する判断の参考になる可能性があるため、削除しないでください）。
3. 提供時に罠が見つかった場合は、pitfalls/<slug>.md を作成します。

TODO エントリーに backlog/ のドキュメントが必要なとき、デバッグに pitfalls/ のドキュメントが必要なとき

判断ルールと AGENTS.md の不変条件への昇格手順は、references/when-to-add-docs.md に記載されています。ハーネスを初めて設定するときに読み、知識をどこに記録すべきか迷ったときは、その都度参照してください。

タグのスキーマ

scripts/todo-kanban.sh で検証される、相互に直交する 2 つの軸です。スキーマ全体、有用なタグの組み合わせ、検証でチェックされる正確な構文については、references/tag-schema.md を参照してください。

アンチパターン

避けるべきよくある間違い（TODO.md と並べて IDEAS.md を作成する、根本原因を pitfall のタイトルにする、エラーを言い換えるなど）です。全リストは references/anti-patterns.md にあります。

デプロイ対象からの除外

TODO.md、backlog/、pitfalls/ はメンテナー向けのリポジトリメタデータであり、配布するファイルではありません。chezmoi／npm／pip／Docker 用のチートシートは references/deployment-exclusion.md にあります。 scripts/init.sh --deployment ... は、追加する正確な行を出力します。

テンプレートと同梱アセット

• assets/TODO.md.template — 各レーンの項目例を含む TODO.md のひな形
• assets/backlog-README.md.template — backlog/ のインデックスと追加ルール
• assets/backlog-doc.md.template — backlog ドキュメント単体（コンテキスト優先）
• assets/pitfalls-README.md.template — pitfalls/ のインデックスと、別の場所で記録された罠への相互参照テーブル
• assets/pitfall-doc.md.template — pitfall ドキュメント単体（症状優先）
• assets/agent-guidance.md.template — AGENTS.md／CLAUDE.md 用のスニペット
• assets/readme-roadmap.md.template — プロジェクトの README.md 用のスニペット
• scripts/init.sh — 一括セットアップ
• scripts/todo-kanban.sh — バリデーターと Markdown カンバンレンダラー （--json と --validate-only にも対応）
• scripts/add-todo.sh — ## P* レーンへの構造化された挿入。 --backlog を指定すると backlog/<slug>.md もひな形から作成
• scripts/promote-todo.sh — 再検証を伴う、アクティブ項目から Done へのアトミックな移動
• scripts/sweep-inbox.sh — backlog/inbox.md をトリアージして add-todo.sh に渡す

参考実装

このハーネスの実際の使用例は daviddwlee84/dotfiles にあります。

• リポジトリルートに TODO.md、backlog/、pitfalls/ ディレクトリ
• AGENTS.md の ### Long-term backlog → TODO.md + backlog/ セクションと ### Past pitfalls → pitfalls/ セクション
• README.md の ## Roadmap & lessons learned セクション