人が方向を定め、エージェントがコードを書き、book がすべてを覚える。
BoCode はリポジトリを二つに分けます——ソースを置く code/ と、ドキュメントの流れとナレッジベースを置く book/ です。両者は双方向に接続されます。今のソフトウェアが実際に書かれている方法、つまり人間と AI コーディングエージェントの共同開発を前提に設計されています。エージェントは速く、メモリもありますが、その記憶はエージェントだけのもの：人間には読めず、管理もできません。プロジェクトの知識がどこに置かれ、誰が読めるかが、速さが制御とともにあるか、制御のない速さになるかを決めます。
すでにプロジェクトがある？ この一行を AI エージェントに貼り付けてください：
https://github.com/Focus695/BoCode を読み（まず ADOPT.md から）、その手順どおりにこのプロジェクトを BoCode ワークフローへ移行してください。
ゼロから始める？ クイックスタートへ直接どうぞ。
AI エージェントで開発するプロジェクトは、ほぼ必ず三つの問題にぶつかります。
- 記憶はエージェントだけのもの。 今のエージェントにはメモリがありますが、それはブラックボックスです：人間には読めず、管理もできません。何が進み、どこでつまずき、何が修正待ちなのか——人間には何も見えない。エージェントが速いほど、人間のコントロール感は薄れます。足りないのは記憶ではなく、人間とエージェントが共に読む場所：進捗のまとめ、既知の罠、修正待ちリスト、プロジェクトの指針。エージェントはそこから働き、人間はそこで舵を取ります。
- ドキュメントは腐る。 立ち上げ時に一度書かれ、二度と更新されない。更新の利益は後で、スキップの利益は今なので、更新は常に後回しにされます。やがて誰も信じなくなります——古いドキュメントは信じる価値がありません。
- 人間がハンドルを失う。 エージェントは頼まれたものに加えて、頼まれていない十二個の変更も実装します。ゲートのないスピードは、スコープの漂移と意思決定の未記録と、「なぜ」の蒸発を意味します。
三つとも同じ根っこを指しています：知識と制御は、チャット履歴でも誰かの記憶でもない場所に住む必要がある、と。
BoCode の答えは構造です。プロジェクトには二つの半分があります。
code/は実行可能な真実——「いまどう動いているか」に答えるbook/はナビゲート可能な真実——「なぜこう動いているか、何を決め、何を学んだか」に答える
どちらも必須です。book のない code は書き込み専用です：動くが、なぜこの形なのかを人間もエージェントも安くは知り得ない。code のない book は日記です。二つはトップレベルに並んで置かれ、永遠に見えるので、どちらかが静かに忘れられることはありません。
二つの半分が互いを駆動します：
book/ (ナレッジベース + 駆動源)
┌─────────────────────────────────────┐
│ plans/ → 実装を駆動 │
│ guidelines/ → ベースラインを提供 │
│ learn/ → 経験を提供 │
│ issue/ → 方向性を提供 │
│ decisions/ → 文脈を提供 │
└──────────────┬──────────────────────┘
│ 駆動
▼
code/
│ 産出
▼
┌─────────────────────────────────────┐
│ summary/ ← 機能の報告書 │
│ learn/ ← 新しい経験 │
│ issue/ ← 発見された問題 │
│ changelogs/ ← 変更記録 │
│ plans/ ← 完了ステータス │
└─────────────────────────────────────┘
book → code：実装の前に、エージェントは plan（施工図）、guidelines（ベースライン）、関連する learn エントリ（蓄積された経験）、未解決の issue（既知の地雷）を読みます。
code → book：作業が終わったらクローズアップで書き戻します——人間が diff を開かずに読める summary、次のセッションが検索できる learn、記録はするがあえて直さない issue、changelog の一行、そして再生成されたインデックス。
これがフライホイールです：一周ごとに book は前より完全になり、すべてのセッション——人間もエージェントも、今日も一年後も——これまでの学びの上から始まります。book が完全なほど、次にプロジェクトに触れるすべての人への価値が高まる。 開発はリセットではなく複利になります。
BoCode のルールは四つのスキルが分担し、それぞれ独立して呼び出されます：
| スキル | 中国語名 | 担当 | トリガー |
|---|---|---|---|
bocode |
薄码 | 構造マップとセッションの規律 | セッション開始時；ドキュメントの居場所 |
boscope |
薄界 | 六段階のゲート——スコープを薄く、ゲートを硬く | 「実装して／変更して」 |
book-writeback |
返写 | 書き戻しテンプレートと品質基準 | 機能の締めくくり；summary / learn / issue |
bowrite |
薄写 | 薄く、うまく書く——文は減り、核は変わらない | 文書の執筆・改訂時 |
以下の節はルール本体、スキルはその実行層です。
すべての機能は六段階のワークフローを硬いゲート付きで通ります（ルール本体は book/guidelines/workflow.md）：
| フェーズ | 産出 | ゲート |
|---|---|---|
| Step 0 — 要件ブリーフ | 背景、スコープ、除外項目、要件 | 全スロット記入 |
| 1 — 分析 | 影響マップ + リスク一覧 | コードは一行も変更しない |
| 2 — 設計 | データフロー、ファイル、インターフェース | ユーザーの承認が必要 |
| 3 — 実装 | コード | 承認されたスコープの外には手を出さない |
| 4 — テスト | テスト（先に書く） | 全グリーン、アサーションを弱めない |
| 5 — レビュー | 発見事項リスト | 記録のみ、その場で直さない |
| 6 — クローズアップ | summary、learn、issue、changelog、インデックス | 記録のみ、その場で直さない |
除外リストは Step 0 の急所です：空の「影響しない」リストこそ、Phase 3 でのスコープ外変更の最大の原因になります。
設計意図：エージェントは実装を分単位に圧縮するので、ボトルネックは意思決定とスコープに移ります。ゲートはまさにそこを守ります——Step 0 が要求に書かれていないことを埋め、Phase 2 で人が方向を承認し、Phase 5〜6 が観察と修正の分離を強制します。レビューで見つかった問題は記録された issue になり、直すのは別の仕事です。 記録のみにすることで、レビューの結論が信頼に足ります。
book のドキュメントは産出物の種類ではなく読者で振り分けます（book/notes/）：
| 種類 | 読者 | 形 |
|---|---|---|
summary/ |
人間 first | 報告書：背景 → 何をしたか → なぜ → 結果 |
learn/ |
人間 + エージェント | タグ付きの検索可能なナレッジエントリ——"timeout" のような症状タグも含む |
issue/ |
人間 + エージェント | 問題 + 再現 + 修正方向の提案 |
task/ |
タスク管理 | チェックリスト |
diff を読まないと分からない summary は summary ではありません。タイトルだけで質問に答えられない learn は、次のセッションに検索されません。book/notes/README.md のテンプレートが品質基準で、締めくくりの書き戻しは book-writeback スキルが担います。
見つけられないドキュメントは、存在しないのと同じです。BoCode は発見可能性をビルドチェックにします：
- すべての book ドキュメントは frontmatter の
descriptionで始まる——体裁ではなく内容を語る、人の言葉で一行 code/tools/gen-book-index.mjs（依存ゼロ、プレーン Node）がbook/README.md——全ドキュメントのマスターインデックス——を再生成する- description の欠けたドキュメントはビルドを失敗させる（exit 1）。ゼロ警告だけが合格です
- 内部リンクは解決必須——切れたリンクもビルドを失敗させます。book は vault を兼ねるため、切れたリンクはビルドバグです
book/README.md は入口も兼ねます：エージェントはまずここで地図を手に入れる。フォルダはそのまま Obsidian の vault として開けます——インデックス、タグ、バックリンク、グラフがすべて使えます（FAQ 参照）。
ドキュメントは何年も読まれ、数分で書かれる。だからスタイル規則は短く厳格です（book/guidelines/writing-style.md）：具体的な人が具体的な状況で話すように書く——プロフェッショナルで構わないが、テンプレート的なのは不可。薄く：文は減り、核は変わらない——削るのは言葉であって情報ではない。うまく：自然に、直接に、無理な小賢しさなく、事実は固定——数値・コマンド・名前・責任の所在は動かさない。bowrite は MrGeDiao の shuorenhua と本プロジェクトのレビューで蓄積したパターン台帳から蒸留されています。
git 履歴は book の一部です（book/guidelines/git-workflow.md）。マージ以外のすべてのコミットは Clean Commit 形式——📦 new (index): add book index generator——に従い、ブランチは Clean Flow モデル（work → dev → main）に従います。両スペックはドキュメントしか同梱しておらず、BoCode はそのギャップを、依存ゼロのバリデータ（ローカル .githooks/ と CI .github/workflows/git-policy.yml）で埋めます。運用では：dev はソロ開発者の統合ブランチで、検証済みの小さな修正は直接 land する。大きな機能はワークブランチを切り、main は dev からのマージコミットだけを受け取ります。
BoCode は自分自身の最初のユーザーです：基盤は構造化された要件ブリーフ、承認された設計プラン、段階的な実装とステップごとの検証、Clean Commit の履歴を通りました——物語全体は git ログで読めます。あなたが受け取るテンプレートはきれいです：日付付きの記録も残された plan もなく、book は空で、あなたのものを待っています。意図的に一つだけ同梱されているのは ADR-001——このワークフローで動くという意思決定であり、あなたのプロジェクトが最初に再確認する決定でもあります。
# 1. このテンプレートからリポジトリを作成（GitHub の "Use this template"）
# またはクローン：
git clone <your-fork-url> myproject && cd myproject
# 2. テンプレートをあなたのプロジェクトに変える（名前、説明、記録のクリーンアップ）：
bash scripts/init-project.sh myproject "What it does, in one line"
# 3. AI エージェントに四つのスキルをインストール：
cp -r skills/bocode skills/boscope skills/book-writeback skills/bowrite <your-skills-dir>/
# (ZCode: ~/.zcode/skills/ · Claude Code: ~/.claude/skills/ — 詳細は skills/README.md)
# 4. エージェントを AGENTS.md に向ける——ほとんどのツールが自動で読みます。
# あとは何かを作るだけ。スキルがワークフローを駆動します。必要なもの：bash と node（二つのスクリプト用）。パッケージなし、インストールステップなし、lockfile なし——ツールチェーンは意図的に退屈に作られています。
| パス | 内容 |
|---|---|
AGENTS.md |
AI エージェントの入口——構造、ルール、ハード制約 |
book/guidelines/ |
ルールブック：ワークフロー、文書スタイル、git、レビュー |
book/README.md |
マスターインデックス（生成物——ここから始める） |
book/plans/ |
実装プラン（施工図） |
book/notes/{summary,learn,task,issue}/ |
四種類のノート |
book/docs/{architecture,api,decisions}/ |
スナップショット、契約、ADR |
skills/ |
bocode、boscope、book-writeback、bowrite |
code/tools/gen-book-index.mjs |
インデックスジェネレータ |
scripts/init-project.sh |
テンプレート → あなたのプロジェクト |
scripts/check-commit-message.mjs |
Clean Commit バリデータ（.githooks/ 付き） |
すでに存在するプロジェクトに BoCode を導入できますか？
はい——ADOPT.md を AI エージェントに渡してください。エージェント向けに書かれた段階的な移行プレイブックです：棚卸し、book スケルトン、レイアウト決定、ドキュメント移行、ツールチェーン、スキル、最初の書き戻し。手動の道もあります：book/、skills/、scripts/、.githooks/、AGENTS.md、code/tools/ をコピーし、既存ドキュメントを book に統合し、インデックスジェネレータを実行するだけです。
言語やスタックに縛られますか？
いいえ。book は Markdown、二つのスクリプトは依存ゼロのプレーン Node です。code/ には何を置いても構いません——テンプレート自身の code/ にはツールしか入っていません。
どの AI ツールで動きますか？
AGENTS.md を指示ファイルとして読み、SKILL.md 形式をサポートするものなら何でも（ZCode、Claude Code、互換エージェント）。スキルがなくてもワークフローは劣化なしで機能します：guidelines が同じルールを文章で運びます。
book は Obsidian などの PKM ツールで読めますか？
はい、設定なしで。book は純粋な Markdown です——相対リンク、YAML frontmatter（description、tags）、独自形式は一切なし。book/ を Obsidian の vault として開けば、インデックス、タグ、バックリンク、グラフがすべて使えます。ビルドはリンクも検証し、切れたリンクはビルドを失敗させるため、開くものはいつも辿れる網です。Obsidian 固定でもありません：Logseq、Foam、VS Code、Markdown を読めるものなら何でも。
インデックスを再生成しないとどうなりますか？ 実行時には何も壊れません——しかしインデックスが古くなれば、システム全体が依存する発見可能性が崩れていきます。だからこそチェックは、description の欠落を派手に失敗させます。
機能ごとのフォルダではなく YYYY-MM/ なのはなぜ？
月は安定した低メンテナンスの物理グルーピングです。機能はインデックス、frontmatter、リンクで見つかる——数ヶ月にわたる機能を毎回切り刻むディレクトリのネストではなく。
BoCode の git 規律は WGTech Labs の二つのオープンスタンダード——Clean Commit（コミットメッセージ形式）と Clean Flow（ブランチモデル）——の上に構築され、両スペックが記述するが同梱しない実行ツールを追加しています。人の言葉で書くスタイルは MrGeDiao の shuorenhua に由来し、bowrite スキルへ蒸留されています。