From a175f24a5b54fd898f07ea44e84d739ff6dee0f2 Mon Sep 17 00:00:00 2001 From: Focus Date: Mon, 14 Sep 2026 11:24:52 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=94=A7=20update=20(skills):=20rename?= =?UTF-8?q?=20feature-flow=20to=20boscope=20and=20name=20all=20four=20skil?= =?UTF-8?q?ls?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ADOPT.md | 4 ++-- scripts/init-project.sh | 2 +- skills/README.md | 8 ++++---- skills/bocode/SKILL.md | 4 ++-- skills/book-writeback/SKILL.md | 4 ++-- skills/{feature-flow => boscope}/SKILL.md | 10 +++++++--- 6 files changed, 18 insertions(+), 14 deletions(-) rename skills/{feature-flow => boscope}/SKILL.md (85%) diff --git a/ADOPT.md b/ADOPT.md index 730e3dc..cb173fa 100644 --- a/ADOPT.md +++ b/ADOPT.md @@ -4,7 +4,7 @@ ## What you are installing -BoCode gives a project two half-brains: `code/` (the source) and `book/` (the documentation stream and knowledge base), driving each other in both directions. You will install: the `book/` skeleton, the index tooling, the git policy tooling (optional), the four skills, and an `AGENTS.md` entry point. You will migrate the project's existing docs into the book. You will **not** refactor any code. +BoCode gives a project two halves: `code/` (the source) and `book/` (the documentation stream and knowledge base), driving each other in both directions. You will install: the `book/` skeleton, the index tooling, the git policy tooling (optional), the four skills, and an `AGENTS.md` entry point. You will migrate the project's existing docs into the book. You will **not** refactor any code. Before starting, read in the BoCode repository: `AGENTS.md`, `book/guidelines/workflow.md`, and `skills/README.md` — this playbook assumes you know the target shape. @@ -53,7 +53,7 @@ Every migrated file gets a frontmatter `description` — one plain-language line ## Step 5 — Install the skills -Copy `skills/bocode`, `skills/feature-flow`, `skills/book-writeback`, and `skills/bowrite` into the agent's skills directory (see BoCode's `skills/README.md` for per-tool locations). If the user's agent can't install skills, the workflow still works — the guidelines carry the same rules in prose. +Copy `skills/bocode`, `skills/boscope`, `skills/book-writeback`, and `skills/bowrite` into the agent's skills directory (see BoCode's `skills/README.md` for per-tool locations). If the user's agent can't install skills, the workflow still works — the guidelines carry the same rules in prose. ## Step 6 — Write the project's `AGENTS.md` diff --git a/scripts/init-project.sh b/scripts/init-project.sh index 87b5424..7edb486 100755 --- a/scripts/init-project.sh +++ b/scripts/init-project.sh @@ -115,7 +115,7 @@ fi echo echo "Done. Next steps:" echo " 1. Install the skills:" -echo " cp -r skills/bocode skills/feature-flow skills/book-writeback skills/bowrite /" +echo " cp -r skills/bocode skills/boscope skills/book-writeback skills/bowrite /" echo " 2. Point your AI agent at AGENTS.md (most tools pick it up automatically)." echo " 3. Fill in book/guidelines/architecture.md and coding-style.md for your project." echo " 4. Set your remote:" diff --git a/skills/README.md b/skills/README.md index 12339dd..c697eaf 100644 --- a/skills/README.md +++ b/skills/README.md @@ -4,9 +4,9 @@ Four self-contained skills implement the BoCode workflow for AI agents. Each is | Skill | Does | Triggers | |-------|------|----------| -| `bocode` | The structure map and the session discipline — read before coding, write back after | Session start in a BoCode repo; questions about where documents go or how the index works | -| `feature-flow` | Step-0 requirements brief + six hard-gated phases for feature development | "Implement / add / support / change X" with a sparse request | -| `book-writeback` | Templates and quality gates for writing back to the book | Feature wrap-up; "write a summary / learn entry / issue" | +| `bocode` | The entry skill（薄码）: structure map and session discipline — read before coding, write back after | Session start in a BoCode repo; questions about where documents go or how the index works | +| `boscope` | The feature-development skill（薄界）: Step-0 requirements brief + six hard-gated phases — scope it thin, gate it hard | "Implement / add / support / change X" with a sparse request | +| `book-writeback` | The write-back skill（返写）: templates and quality gates for writing back to the book | Feature wrap-up; "write a summary / learn entry / issue" | | `bowrite` | The writing skill（薄写）: write documents thin and well — fewer words, same core, natural voice | Writing or revising any document; drafts that smell templated, translated, or strained | Division of labor: **skills say when and how** (executable behavior for the agent); **`book/guidelines/` says what and why** (reference for humans). They reference each other and never duplicate rules. @@ -20,7 +20,7 @@ Copy the four skill directories into your agent's skills folder: - **Other SKILL.md-compatible agents**: the skills directory your tool documents ```bash -cp -r skills/bocode skills/feature-flow skills/book-writeback skills/bowrite / +cp -r skills/bocode skills/boscope skills/book-writeback skills/bowrite / ``` `bowrite` distills [shuorenhua](https://github.com/MrGeDiao/shuorenhua) (MIT, by MrGeDiao) together with patterns accumulated in this project's own reviews; for deep Chinese cleanups the upstream skill goes further and is worth installing alongside. diff --git a/skills/bocode/SKILL.md b/skills/bocode/SKILL.md index 4291848..7f80f66 100644 --- a/skills/bocode/SKILL.md +++ b/skills/bocode/SKILL.md @@ -1,9 +1,9 @@ --- name: bocode -description: Entry skill for repositories running the BoCode workflow (code/ + book/ layout). Use when a session starts in such a repo, or when deciding where a document goes, how the book index works, or what the code↔book rules require. Teaches the structure map and the discipline; feature development itself is handled by feature-flow. +description: Entry skill（中文名：薄码）for repositories running the BoCode workflow (code/ + book/ layout). Use when a session starts in such a repo, or when deciding where a document goes, how the book index works, or what the code↔book rules require. Teaches the structure map and the discipline; feature development itself is handled by boscope. --- -# bocode +# bocode（薄码） This repository runs BoCode: `code/` is the source, `book/` is the documentation stream and knowledge base. They drive each other in both directions. Your job in every session: keep the flywheel spinning — read from the book before coding, write back to the book after. diff --git a/skills/book-writeback/SKILL.md b/skills/book-writeback/SKILL.md index fed035a..65a716c 100644 --- a/skills/book-writeback/SKILL.md +++ b/skills/book-writeback/SKILL.md @@ -1,9 +1,9 @@ --- name: book-writeback -description: Guides writing back to the book after work completes — summary reports, learn entries, issue records, changelog entries — with templates and quality gates, then regenerating the index. Use at feature wrap-up, after small fixes that taught something, or when the user asks to write a summary, learn entry, issue, or changelog. +description: The write-back skill（中文名：返写）— guides writing back to the book after work completes: summary reports, learn entries, issue records, changelog entries, with templates and quality gates, then regenerating the index. Use at feature wrap-up, after small fixes that taught something, or when the user asks to write a summary, learn entry, issue, or changelog. --- -# book-writeback +# book-writeback（返写） Development that doesn't write back to the book loses its experience. This skill covers what to write, where, and the quality bar — for the BoCode layout (`book/` with `notes/{summary,learn,issue}/`, `changelogs/`, `plans/`). diff --git a/skills/feature-flow/SKILL.md b/skills/boscope/SKILL.md similarity index 85% rename from skills/feature-flow/SKILL.md rename to skills/boscope/SKILL.md index c2e58d4..5caa769 100644 --- a/skills/feature-flow/SKILL.md +++ b/skills/boscope/SKILL.md @@ -1,9 +1,13 @@ --- -name: feature-flow -description: Splits a feature into a Step-0 structured requirements brief plus six hard-gated phases (analysis, design, implementation, testing, review, wrap-up). Use when the user asks to implement/add/support/change a feature and the request is sparse — missing background, scope, or detailed logic. Do not use for one-line fixes, typos, pure questions, or tasks whose scope the user has already fully specified. +name: boscope +description: BoCode's feature-development skill（中文名：薄界）— scope it thin, gate it hard. Splits a feature into a Step-0 structured requirements brief plus six hard-gated phases (analysis, design, implementation, testing, review, wrap-up). Use when the user asks to implement/add/support/change a feature and the request is sparse — missing background, scope, or detailed logic. Do not use for one-line fixes, typos, pure questions, or tasks whose scope the user has already fully specified. --- -# feature-flow +# BoScope（薄界） + +Scope it thin. Gate it hard. + +薄界：把界画清——范围、排除、边界先说死，再动代码；阶段一关一关过，不许跳。与 BoWrite 成对：薄写把书写薄，薄界把界画薄——内容薄、边界也薄，薄到一眼见底。 ## Goal From c27a1f33f5e074a5ab247b4b03e29528d906f331 Mon Sep 17 00:00:00 2001 From: Focus Date: Mon, 14 Sep 2026 11:24:52 +0800 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=93=96=20docs:=20rework=20readme=20pi?= =?UTF-8?q?tch=20with=20dual-reader=20framing=20and=20new=20slogan?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/assets/banner.svg | 4 +- AGENTS.md | 2 +- README.ja.md | 45 +++++++++++++-------- README.md | 43 +++++++++++++------- README.zh-CN.md | 41 ++++++++++++------- book/docs/decisions/ADR-001-adopt-bocode.md | 2 +- book/guidelines/workflow.md | 2 +- 7 files changed, 89 insertions(+), 50 deletions(-) diff --git a/.github/assets/banner.svg b/.github/assets/banner.svg index 950aefa..92b77ee 100644 --- a/.github/assets/banner.svg +++ b/.github/assets/banner.svg @@ -18,6 +18,6 @@ BoCode - Documentation drives code. Code writes back. - code/ + book/ — two half-brains, one flywheel + Humans steer. Agents build. + the book remembers everything diff --git a/AGENTS.md b/AGENTS.md index e9e289b..d296655 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,7 +16,7 @@ This project runs on the **BoCode workflow**: `code/` holds the source, `book/` └── book/ # documentation stream and knowledge base ``` -**code and book are the project's two half-brains — neither is optional.** The relationship runs both ways: +**code and book are the project's two halves — neither is optional.** The relationship runs both ways: - **book → code**: plans drive implementation; guidelines provide the baseline; learn entries supply experience to consult before coding; issues provide direction for later iterations. - **code → book**: after code changes, check whether book needs syncing; when a feature completes, write its summary / learn / issue back into book. diff --git a/README.ja.md b/README.ja.md index 970ed0d..a656720 100644 --- a/README.ja.md +++ b/README.ja.md @@ -1,5 +1,5 @@

- BoCode — ドキュメントがコードを駆動し、コードがドキュメントに書き戻す + BoCode — 人が方向を定め、エージェントが書き、book が覚える

@@ -12,9 +12,9 @@ Use this template

-**ドキュメントがコードを駆動し、コードがドキュメントに書き戻す、プロジェクトテンプレート。** +**人が方向を定め、エージェントがコードを書き、book がすべてを覚える。** -BoCode はリポジトリに二つの半脳を与えます——ソースを置く `code/` と、ドキュメントの流れとナレッジベースを置く `book/` です。両者は双方向に接続されます。今のソフトウェアが実際に書かれている方法、つまり人間と AI コーディングエージェントの共同開発を前提に設計されています。プロジェクトが複利的に成長するか、セッションごとにゼロリセットされるかは、知識が耐久性のある場所に置かれているかどうかで決まります。 +BoCode はリポジトリを二つに分けます——ソースを置く `code/` と、ドキュメントの流れとナレッジベースを置く `book/` です。両者は双方向に接続されます。今のソフトウェアが実際に書かれている方法、つまり人間と AI コーディングエージェントの共同開発を前提に設計されています。エージェントは速く、メモリもありますが、その記憶はエージェントだけのもの：人間には読めず、管理もできません。プロジェクトの知識がどこに置かれ、誰が読めるかが、速さが制御とともにあるか、制御のない速さになるかを決めます。 ## 一行で導入 @@ -24,7 +24,7 @@ BoCode はリポジトリに二つの半脳を与えます——ソースを置 https://github.com/Focus695/BoCode を読み（まず ADOPT.md から）、その手順どおりにこのプロジェクトを BoCode ワークフローへ移行してください。 ``` -ゼロから始める？ 三コマンドのクイックスタートは下にあります。 +ゼロから始める？ [クイックスタート](#クイックスタート)へ直接どうぞ。 --- @@ -34,13 +34,13 @@ https://github.com/Focus695/BoCode を読み（まず ADOPT.md から）、そ AI エージェントで開発するプロジェクトは、ほぼ必ず三つの問題にぶつかります。 -1. **エージェントは状態を持たない。** セッションは毎回ゼロから始まります。書き残されていない知識は、再導出され、再質問され、再破壊されます。 +1. **記憶はエージェントだけのもの。** 今のエージェントにはメモリがありますが、それはブラックボックスです：人間には読めず、管理もできません。何が進み、どこでつまずき、何が修正待ちなのか——人間には何も見えない。エージェントが速いほど、人間のコントロール感は薄れます。足りないのは記憶ではなく、人間とエージェントが共に読む場所：進捗のまとめ、既知の罠、修正待ちリスト、プロジェクトの指針。エージェントはそこから働き、人間はそこで舵を取ります。 2. **ドキュメントは腐る。** 立ち上げ時に一度書かれ、二度と更新されない。更新の利益は後で、スキップの利益は今なので、更新は常に後回しにされます。やがて誰も信じなくなります——古いドキュメントは信じる価値がありません。 3. **人間がハンドルを失う。** エージェントは頼まれたものに加えて、頼まれていない十二個の変更も実装します。ゲートのないスピードは、スコープの漂移と意思決定の未記録と、「なぜ」の蒸発を意味します。 三つとも同じ根っこを指しています：知識と制御は、チャット履歴でも誰かの記憶でもない場所に住む必要がある、と。 -### 二つの半脳 +### それぞれが半分を担う BoCode の答えは構造です。プロジェクトには二つの半分があります。 @@ -86,13 +86,24 @@ BoCode の答えは構造です。プロジェクトには二つの半分があ ## 手法 -### ブレーキではなくゲート +BoCode のルールは四つのスキルが分担し、それぞれ独立して呼び出されます： -すべての機能は六段階のワークフローを硬いゲート付きで通ります（`book/guidelines/workflow.md`、振る舞いは `feature-flow` スキルが強制）： +| スキル | 中国語名 | 担当 | トリガー | +|-------|---------|------|----------| +| `bocode` | 薄码 | 構造マップとセッションの規律 | セッション開始時；ドキュメントの居場所 | +| `boscope` | 薄界 | 六段階のゲート——スコープを薄く、ゲートを硬く | 「実装して／変更して」 | +| `book-writeback` | 返写 | 書き戻しテンプレートと品質基準 | 機能の締めくくり；summary / learn / issue | +| `bowrite` | 薄写 | 薄く、うまく書く——文は減り、核は変わらない | 文書の執筆・改訂時 | + +以下の節はルール本体、スキルはその実行層です。 + +### boscope（薄界）——ブレーキではなくゲート + +すべての機能は六段階のワークフローを硬いゲート付きで通ります（ルール本体は `book/guidelines/workflow.md`）： | フェーズ | 産出 | ゲート | |-------|--------|------| -| Step 0 — 要件ブリーフ | 背景、スコープ、除外項目、要件 | 全スロット記入——**除外リストは必須**。空の除外リストがスコープ外変更の最大の原因 | +| Step 0 — 要件ブリーフ | 背景、スコープ、除外項目、要件 | 全スロット記入 | | 1 — 分析 | 影響マップ + リスク一覧 | コードは一行も変更しない | | 2 — 設計 | データフロー、ファイル、インターフェース | **ユーザーの承認が必要** | | 3 — 実装 | コード | 承認されたスコープの外には手を出さない | @@ -100,7 +111,9 @@ BoCode の答えは構造です。プロジェクトには二つの半分があ | 5 — レビュー | 発見事項リスト | 記録のみ、その場で直さない | | 6 — クローズアップ | summary、learn、issue、changelog、インデックス | 記録のみ、その場で直さない | -設計意図：エージェントは実装を分単位に圧縮するので、ボトルネックは意思決定とスコープに移ります。ゲートは人間の手をまさにそこに置きます——Step 0 が要求に書かれていないことを埋め、Phase 2 で人が方向を承認し、Phase 5〜6 が観察と修正の分離を強制します。**レビューで見つかった問題は記録された issue になり、直すのは別の仕事です。** その場で直させないゲートこそが、レビューを正直に保つゲートです。 +除外リストは Step 0 の急所です：空の「影響しない」リストこそ、Phase 3 でのスコープ外変更の最大の原因になります。 + +設計意図：エージェントは実装を分単位に圧縮するので、ボトルネックは意思決定とスコープに移ります。ゲートはまさにそこを守ります——Step 0 が要求に書かれていないことを埋め、Phase 2 で人が方向を承認し、Phase 5〜6 が観察と修正の分離を強制します。**レビューで見つかった問題は記録された issue になり、直すのは別の仕事です。** 記録のみにすることで、レビューの結論が信頼に足ります。 ### 読者のために書く @@ -111,9 +124,9 @@ book のドキュメントは産出物の種類ではなく読者で振り分け | `summary/` | 人間 first | 報告書：背景 → 何をしたか → なぜ → 結果 | | `learn/` | 人間 + エージェント | タグ付きの検索可能なナレッジエントリ——"timeout" のような症状タグも含む | | `issue/` | 人間 + エージェント | 問題 + 再現 + 修正方向の提案 | -| `task/` | 作業メモリ | チェックリスト | +| `task/` | タスク管理 | チェックリスト | -diff を読まないと分からない summary は summary ではありません。タイトルだけで質問に答えられない learn は、次のセッションに検索されません。`book/notes/README.md` のテンプレートが品質基準を示しています。 +diff を読まないと分からない summary は summary ではありません。タイトルだけで質問に答えられない learn は、次のセッションに検索されません。`book/notes/README.md` のテンプレートが品質基準で、締めくくりの書き戻しは `book-writeback` スキルが担います。 ### インデックス契約 @@ -125,9 +138,9 @@ diff を読まないと分からない summary は summary ではありません `book/README.md` は入口も兼ねます：エージェントはまずここで地図を手に入れる。フォルダはそのまま [Obsidian](https://obsidian.md) の vault として開けます。 -### 人の言葉で書く +### bowrite（薄写）——人の言葉で書く -ドキュメントは何年も読まれ、数分で書かれる。だからスタイル規則は短く厳格です（`book/guidelines/writing-style.md`）：具体的な人が具体的な状況で話すように書く——プロフェッショナルで構わないが、テンプレート的なのは不可。埋め草の前置きと空っぽのまとめを削り、事実は固定する——数値・コマンド・名前・責任の所在は動かさない。この基準は `bowrite` スキル（薄写：薄く書く——文は減り、核は変わらない；うまく書く——自然に、直接に）がエージェント側で担い、MrGeDiao の [shuorenhua](https://github.com/MrGeDiao/shuorenhua) と本プロジェクトのレビューで蓄積したパターンから蒸留されています。 +ドキュメントは何年も読まれ、数分で書かれる。だからスタイル規則は短く厳格です（`book/guidelines/writing-style.md`）：具体的な人が具体的な状況で話すように書く——プロフェッショナルで構わないが、テンプレート的なのは不可。薄く：文は減り、核は変わらない——削るのは言葉であって情報ではない。うまく：自然に、直接に、無理な小賢しさなく、事実は固定——数値・コマンド・名前・責任の所在は動かさない。bowrite は MrGeDiao の [shuorenhua](https://github.com/MrGeDiao/shuorenhua) と本プロジェクトのレビューで蓄積したパターン台帳から蒸留されています。 ### クリーンな git フロー @@ -150,7 +163,7 @@ git clone myproject && cd myproject bash scripts/init-project.sh myproject "What it does, in one line" # 3. AI エージェントに四つのスキルをインストール： -cp -r skills/bocode skills/feature-flow skills/book-writeback skills/bowrite / +cp -r skills/bocode skills/boscope skills/book-writeback skills/bowrite / # (ZCode: ~/.zcode/skills/ · Claude Code: ~/.claude/skills/ — 詳細は skills/README.md) # 4. エージェントを AGENTS.md に向ける——ほとんどのツールが自動で読みます。 @@ -169,7 +182,7 @@ cp -r skills/bocode skills/feature-flow skills/book-writeback skills/bowrite - BoCode — documentation drives code, code writes back + BoCode — humans steer, agents build, the book remembers

@@ -12,9 +12,9 @@ Use this template

-**A project template where documentation drives code, and code writes back.** +**Humans steer, agents build, the book remembers.** -BoCode gives a repository two half-brains — `code/` for the source, `book/` for the documentation stream and knowledge base — wired together in both directions. It is built for the way software is written now: a human and AI coding agents together. Whether a project compounds or resets every session comes down to whether its knowledge lives somewhere durable. +BoCode gives a repository two halves — `code/` for the source, `book/` for the documentation stream and knowledge base — wired together in both directions. It is built for the way software is written now: a human and AI coding agents together. Agents are fast and have memory now — but that memory serves the agent alone: unreadable to humans, unmanageable. Where a project's knowledge lives, and who can read it, decides whether speed comes with control or without it. ## Adopt it in one line @@ -24,7 +24,7 @@ Already have a project? Paste this to your AI agent: Read https://github.com/Focus695/BoCode — start with ADOPT.md — and retrofit this project onto the BoCode workflow exactly as it prescribes. ``` -Starting from scratch? The three-command Quick Start is below. +Starting from scratch? Jump straight to the [Quick Start](#quick-start). Clone it, run one script, install four skills, and your project gains: a gated development workflow, a self-indexing knowledge base, a write-back discipline that turns every feature into accumulated experience, and a git policy that keeps history readable. @@ -36,13 +36,13 @@ Clone it, run one script, install four skills, and your project gains: a gated d Three failures show up in almost every project built with AI agents: -1. **Agents are stateless.** Every session starts from zero. Knowledge that isn't written down somewhere durable gets re-derived, re-asked, and re-broken. +1. **Memory serves the agent alone.** Agents have memory now, but it's a black box: humans can't read it, let alone manage it. What shipped, what bit us, what's waiting to be fixed — all invisible. The faster the agent moves, the less control the human holds. What's missing isn't memory; it's one shared, readable place: recent summaries, known pitfalls, the open fix list, the project's guidelines. Agents work from it; humans steer by it. 2. **Documentation rots.** Written once at the start, updated never. Because updating it pays off later and skipping it pays off now, it always gets skipped. Eventually nobody trusts it — a stale document doesn't deserve trust. 3. **Humans lose the wheel.** An agent will implement what you asked plus twelve things you didn't. Speed without gates means scope drifts, decisions go unrecorded, and the project's "why" evaporates. Each failure points at the same root: knowledge and control need a place to live that isn't chat history or someone's memory. -### Two half-brains +### Two halves BoCode's answer is structural. A project has two halves: @@ -88,13 +88,24 @@ This is the flywheel: every cycle leaves the book more complete than it found it ## The method -### Gates, not brakes +BoCode's rules are carried by four skills, each invoked independently: -Every feature runs a six-phase workflow with hard gates (`book/guidelines/workflow.md`, enforced in behavior by the `feature-flow` skill): +| Skill | Chinese name | Owns | Triggers | +|-------|--------------|------|----------| +| `bocode` | 薄码 | The structure map and session discipline | Session start; where documents go | +| `boscope` | 薄界 | The six gated phases — scope it thin, gate it hard | "Implement / add / change X" | +| `book-writeback` | 返写 | Write-back templates and quality gates | Feature wrap-up; summary / learn / issue | +| `bowrite` | 薄写 | Write thin and well — fewer words, same core | Writing or revising any document | + +The sections below state the rules; the skills are their enforcement layer. + +### boscope（薄界）— gates, not brakes + +Every feature runs a six-phase workflow with hard gates (the rules live in `book/guidelines/workflow.md`): | Phase | Output | Gate | |-------|--------|------| -| Step 0 — requirements brief | background, scope, exclusions, requirement | Every slot filled — **the exclusions list is required**, an empty one is the top cause of out-of-scope changes | +| Step 0 — requirements brief | background, scope, exclusions, requirement | Every slot filled | | 1 — Analysis | impact map + risk list | No code changed | | 2 — Design | data flow, files, interfaces | **User approval required** | | 3 — Implementation | the code | Nothing outside the approved scope | @@ -102,6 +113,8 @@ Every feature runs a six-phase workflow with hard gates (`book/guidelines/workfl | 5 — Review | findings list | Recorded, never fixed | | 6 — Wrap-up | summary, learn, issues, changelog, index | Recorded, never fixed | +The exclusions list is Step 0's crux: an empty "does not affect" list is the number-one cause of out-of-scope changes in Phase 3. + The design intent: agents compress implementation to minutes, which moves the bottleneck to decisions and scope. The gates hold exactly there — Step 0 fills in what the request didn't say, Phase 2 is where a person approves direction, and Phases 5–6 enforce the separation of observing and fixing. **A problem found at review becomes a recorded issue; fixing it is separate work.** That is what keeps the review honest. ### Write for the reader @@ -113,9 +126,9 @@ Book documents are routed by audience, not by kind of artifact (`book/notes/`): | `summary/` | Humans first | A report: background → what was done → why → outcome | | `learn/` | Humans + agents | A searchable knowledge entry with tags — including symptom tags like "timeout" | | `issue/` | Humans + agents | Problem + reproduction + suggested direction | -| `task/` | Working memory | A checklist | +| `task/` | Task tracking | A checklist | -A summary that requires reading the diff isn't a summary. A learn entry whose title doesn't answer the question won't be found by the next session. The templates in `book/notes/README.md` encode the quality bar. +A summary that requires reading the diff isn't a summary. A learn entry whose title doesn't answer the question won't be found by the next session. The templates in `book/notes/README.md` encode the quality bar, and the `book-writeback` skill carries them at wrap-up. ### The index contract @@ -127,9 +140,9 @@ Documentation you can't find doesn't exist. BoCode makes discoverability a build `book/README.md` doubles as the entry point: agents read it first to get the map; the folder also opens directly as an [Obsidian](https://obsidian.md) vault. -### Speak human +### bowrite（薄写）— speak human -Documentation is read for years and written in minutes, so the style rule is strict and short (`book/guidelines/writing-style.md`): write like a specific person in a specific situation — professional is fine, templated is not. Cut filler openers and empty summaries; keep the facts locked — numbers, commands, names, and responsibility attribution never move. The `bowrite` skill（薄写 — write thin, write well: fewer words, same core）carries this standard for agents; it distills [shuorenhua](https://github.com/MrGeDiao/shuorenhua) by MrGeDiao together with patterns accumulated in this project's own reviews. +Documentation is read for years and written in minutes, so the style rule is strict and short (`book/guidelines/writing-style.md`): write like a specific person in a specific situation — professional is fine, templated is not. Thin: fewer words, same core — cut words, not information. Well: natural, direct, no strained cleverness, facts locked — numbers, commands, names, and responsibility attribution never move. bowrite distills [shuorenhua](https://github.com/MrGeDiao/shuorenhua) by MrGeDiao, plus the pattern ledger accumulated in this project's own reviews. ### Clean git flow @@ -152,7 +165,7 @@ git clone myproject && cd myproject bash scripts/init-project.sh myproject "What it does, in one line" # 3. Install the four skills for your AI agent: -cp -r skills/bocode skills/feature-flow skills/book-writeback skills/bowrite / +cp -r skills/bocode skills/boscope skills/book-writeback skills/bowrite / # (ZCode: ~/.zcode/skills/ · Claude Code: ~/.claude/skills/ — see skills/README.md) # 4. Point your agent at AGENTS.md — most tools read it automatically. @@ -171,7 +184,7 @@ Requirements: `bash` and `node` for the two scripts. No packages, no install ste | `book/plans/` | Implementation blueprints | | `book/notes/{summary,learn,task,issue}/` | The four note types | | `book/docs/{architecture,api,decisions}/` | Snapshots, contracts, ADRs | -| `skills/` | `bocode`, `feature-flow`, `book-writeback`, `bowrite` | +| `skills/` | `bocode`, `boscope`, `book-writeback`, `bowrite` | | `code/tools/gen-book-index.mjs` | The index generator | | `scripts/init-project.sh` | Template → your project | | `scripts/check-commit-message.mjs` | Clean Commit validator (+ `.githooks/`) | diff --git a/README.zh-CN.md b/README.zh-CN.md index 2401325..8844b92 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,5 +1,5 @@

- BoCode — 文档驱动代码，代码回写文档 + BoCode — 人定方向，agent 写码，book 记住一切

@@ -12,9 +12,9 @@ Use this template

-**让文档驱动代码，让代码反过来写文档。** +**人定方向，agent 写码，book 记住一切。** -BoCode 把仓库分成两半：`code/` 放源代码，`book/` 放文档和知识库，两边互相驱动。它是为现在最常见的开发方式设计的：人和 AI agent 一起写代码。agent 快，但没有记忆。项目知识存在哪里，决定了开发是越做越顺，还是每个会话都重新踩一遍坑。 +BoCode 把仓库分成两半：`code/` 放源代码，`book/` 放文档和知识库，两边互相驱动。它是为现在最常见的开发方式设计的：人和 AI agent 一起写代码。agent 快，也有记忆，可记忆只归它自己：人读不懂、管不了。项目知识放在哪里、给谁读，决定了开发是又快又稳，还是快得让人心里没底。 ## 一句话接入 @@ -24,7 +24,7 @@ BoCode 把仓库分成两半：`code/` 放源代码，`book/` 放文档和知识 阅读 https://github.com/Focus695/BoCode（从 ADOPT.md 开始），按照它的步骤把当前项目改造为 BoCode 工作流。 ``` -新开项目？三条命令的快速开始在下面。 +新开项目？直接跳到[快速开始](#快速开始)。 --- @@ -34,13 +34,13 @@ BoCode 把仓库分成两半：`code/` 放源代码，`book/` 放文档和知识 用 AI agent 写代码的项目，几乎都会撞上三件事： -1. **Agent 没有记忆。** 每个会话从零开始。没写下来的知识，每个会话都要重新推导一遍、重新问一遍、重新踩一遍坑。 +1. **记忆只归 agent 自己。** 现在的 agent 都有 memory，可那是个黑盒：人读不懂，也管不了。最近推进了什么、踩过哪些坑、哪些问题等着修，人一概看不见——agent 干得越快，人的掌控感越少。缺的不是记忆，是人和 agent 共读的同一个地方：进展的总结、踩过的坑、待修的问题、项目的指南。agent 靠它干活，人靠它掌舵。 2. **文档会过时。** 立项时写一次，之后没人更新。更新文档的好处要很久之后才看得到，跳过它马上就省事，所以文档总是作用不大。到最后没人信文档——过时的文档确实不值得信。 3. **人抓不住方向盘。** 你让 agent 做一件事，它会顺手多做十二件。速度上去了、关卡没跟上，作用域就开始漂移：改了不该改的，做了没人知道的决定，半年后没人说得清"当时为什么这么做"。 三件事的根源是同一个：知识不能只存在聊天记录和人脑里。 -### 两个半脑 +### 各管一半 BoCode 用结构回答这个问题。一个项目有两半： @@ -86,13 +86,24 @@ BoCode 用结构回答这个问题。一个项目有两半： ## 方法 -### 是关卡，不是刹车 +BoCode 的规矩由四个 skill 分头执行、各自独立调用： -每个功能走六阶段，每阶段是硬关卡（`book/guidelines/workflow.md`，由 `feature-flow` skill 在行为层执行）： +| Skill | 中文 | 管 | 何时出手 | +|-------|------|-----|---------| +| `bocode` | 薄码 | 结构地图与全程纪律 | 会话开始；查文档去向、索引规则 | +| `boscope` | 薄界 | 六阶段关卡——范围先说死，一关一关过 | 要实现 / 改一个功能 | +| `book-writeback` | 返写 | 回写模板与质量线 | 功能收尾；写 summary / learn / issue | +| `bowrite` | 薄写 | 写薄写好——内容变少，核心没变 | 写或改任何文档 | + +下面几节讲规则本身，skill 是它们的执行层。 + +### 薄界（boscope）：是关卡，不是刹车 + +每个功能走六阶段，每阶段是硬关卡（规范本体：`book/guidelines/workflow.md`）： | 阶段 | 产出 | 关卡 | |------|------|------| -| Step 0 需求 Brief | 背景、作用域、排除项、需求 | 每个槽位填实——**排除清单必填**，空着的排除项是越界改动的头号原因 | +| Step 0 需求 Brief | 背景、作用域、排除项、需求 | 每个槽位填实 | | 1 需求分析 | 影响图 + 风险清单 | 不改任何代码 | | 2 设计 | 数据流、文件清单、接口 | **用户确认后才推进** | | 3 实现 | 代码 | 严格按批准的作用域 | @@ -100,6 +111,8 @@ BoCode 用结构回答这个问题。一个项目有两半： | 5 Review | 问题清单 | 只记录，不修复 | | 6 收尾 | summary、learn、issue、changelog、索引 | 只记录，不修复 | +排除清单是 Step 0 的命门：空着的"不影响"清单，就是 Phase 3 越界改动的头号来源。 + 设计意图：agent 把实现压到分钟级，瓶颈就挪到了决策和作用域上，关卡恰好守在那里——Step 0 补上需求没说的话，Phase 2 由人拍板方向，Phase 5/6 把"看"和"改"分开。**Review 时发现的问题进清单，修复是另一件事。** 只记录、不修复，review 的结论才可信。 ### 为读者而写 @@ -113,7 +126,7 @@ book 的文档按读者分流，而不是按文档类型（`book/notes/`）： | `issue/` | 人类 + agent | 问题 + 复现 + 建议方向 | | `task/` | 任务跟踪 | 检查清单 | -要读 diff 才懂的 summary 不是 summary；标题答不了问题的 learn，下个会话也搜不到。`book/notes/README.md` 里的模板就是合格线。 +要读 diff 才懂的 summary 不是 summary；标题答不了问题的 learn，下个会话也搜不到。`book/notes/README.md` 里的模板就是合格线，收尾回写时由 `book-writeback`（返写）skill 带着执行。 ### 索引契约 @@ -125,9 +138,9 @@ book 的文档按读者分流，而不是按文档类型（`book/notes/`）： `book/README.md` 也是入口：agent 先读它拿地图；这个目录还能直接用 [Obsidian](https://obsidian.md) 打开当 vault。 -### 说人话 +### 薄写（bowrite）：说人话 -文档是几分钟写完、要被读好几年的东西，所以风格规则短而严（`book/guidelines/writing-style.md`）：像具体的人在具体场景里说话——专业可以，模板化不行。套话和空总结删掉，事实锁死：数字、命令、名称、责任主体一个不动。这套标准由 `bowrite` skill（薄写：写薄——内容变少、核心不变；写好——自然、直接、不抖机灵）在 agent 侧执行，它蒸馏自 MrGeDiao 的 [shuorenhua](https://github.com/MrGeDiao/shuorenhua)，加上本项目 review 中攒下的表达模式。 +文档是几分钟写完、要被读好几年的东西，所以风格规则短而严（`book/guidelines/writing-style.md`）：像具体的人在具体场景里说话——专业可以，模板化不行。写薄：内容变少、核心没变，删的是字不是信息；写好：自然、直接、不抖机灵，事实锁死——数字、命令、名称、责任主体一个不动。bowrite 蒸馏自 MrGeDiao 的 [shuorenhua](https://github.com/MrGeDiao/shuorenhua)，加上本项目 review 中攒下的表达模式账本。 ### 干净的 git 流 @@ -150,7 +163,7 @@ git clone myproject && cd myproject bash scripts/init-project.sh myproject "一句话说明它是干什么的" # 3. 给你的 AI agent 装上四个 skill： -cp -r skills/bocode skills/feature-flow skills/book-writeback skills/bowrite / +cp -r skills/bocode skills/boscope skills/book-writeback skills/bowrite / # （ZCode: ~/.zcode/skills/ · Claude Code: ~/.claude/skills/ —— 见 skills/README.md） # 4. 让 agent 指向 AGENTS.md——多数工具会自动读。 @@ -169,7 +182,7 @@ cp -r skills/bocode skills/feature-flow skills/book-writeback skills/bowrite