From 032a98613e12adadfd9c481b6e3a20a871ae47e5 Mon Sep 17 00:00:00 2001 From: Focus Date: Mon, 14 Sep 2026 10:27:10 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=A6=20new=20(skills):=20add=20bowr?= =?UTF-8?q?ite=20skill=20with=20thinning=20method=20and=20pattern=20ledger?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ADOPT.md | 4 +- book/README.md | 3 +- book/docs/decisions/ADR-002-adopt-bowrite.md | 32 ++++ book/guidelines/writing-style.md | 2 +- scripts/init-project.sh | 2 +- skills/README.md | 9 +- skills/bocode/SKILL.md | 2 +- skills/bowrite/SKILL.md | 146 +++++++++++++++++++ 8 files changed, 190 insertions(+), 10 deletions(-) create mode 100644 book/docs/decisions/ADR-002-adopt-bowrite.md create mode 100644 skills/bowrite/SKILL.md diff --git a/ADOPT.md b/ADOPT.md index e260765..730e3dc 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 three 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 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. 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` 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/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. ## Step 6 — Write the project's `AGENTS.md` diff --git a/book/README.md b/book/README.md index 52434c3..9958955 100644 --- a/book/README.md +++ b/book/README.md @@ -49,6 +49,7 @@ description: Master index of the book — the map of every document. Regenerate ### docs/decisions/ - [ADR-001-adopt-bocode.md](docs/decisions/ADR-001-adopt-bocode.md) — We run this repository on the BoCode workflow — book drives code, code writes back, six phases gate every feature +- [ADR-002-adopt-bowrite.md](docs/decisions/ADR-002-adopt-bowrite.md) — We distill shuorenhua plus our own review patterns into bowrite (薄写), an in-repo writing skill — write thin, write well - [README.md](docs/decisions/README.md) — How to write an ADR here — sections, naming, numbering, and when a decision needs a record ### guidelines/ @@ -69,4 +70,4 @@ description: Master index of the book — the map of every document. Regenerate - [README.md](plans/README.md) — Plans directory usage — implementation plans land here after Phase 2 approval, with naming and the plan template - + diff --git a/book/docs/decisions/ADR-002-adopt-bowrite.md b/book/docs/decisions/ADR-002-adopt-bowrite.md new file mode 100644 index 0000000..0f43f81 --- /dev/null +++ b/book/docs/decisions/ADR-002-adopt-bowrite.md @@ -0,0 +1,32 @@ +--- +description: We distill shuorenhua plus our own review patterns into bowrite (薄写), an in-repo writing skill — write thin, write well +--- + +# ADR-002: Adopt the bowrite writing skill (薄写) + +## Status + +Accepted — ships with the template. + +## Context + +Every book document is held to a plain-language standard (see [ADR-001](ADR-001-adopt-bocode.md) and `guidelines/writing-style.md`). The full ruleset we drew on, [shuorenhua](https://github.com/MrGeDiao/shuorenhua), is an external MIT project — deeper than our needs for Chinese, but not ours, and the project's policy is to reference third-party skills, never bundle them. + +Meanwhile, the project's own document reviews kept catching the same expression problems that neither the guideline nor the upstream skill names explicitly: cleverness that makes the reader guess (bet-table metaphors, double-metaphors), over-compression that decodes to nothing ("不信也对"), emphasis formulas ("不是X，而是Y" / "正是……的原因"), colloquial words crossing into written text ("根子" → "根源"), terms borrowed from other fields ("工作记忆" for task tracking), and translation-ese in multilingual documents. These patterns accumulate with every review. + +## Decision + +Add a fourth skill, `bowrite`（中文名：薄写 — write thin, write well: 内容变少，核心没变）： + +- **Thin**: fewer words, zero information lost — 把书读薄 happens at writing time +- **Well**: natural, direct, the reader's language — never clever at the cost of clear +- It carries a **living pattern ledger**: every new expression problem caught in review is added as a before/after entry, so the skill grows with the project +- It distills shuorenhua's principles with attribution kept; the upstream skill remains the reference for deep Chinese cleanup and is never bundled +- `guidelines/writing-style.md` stays as the prose fallback for environments without skills + +## Consequences + +- Agents installing the skills get an executable writing standard in every project, not just prose rules +- The project's review findings now compound into the skill instead of living in one-off fixes +- Three layers must stay distinct: skill = when/how for agents, guideline = what/why for humans, upstream = deep Chinese ruleset — duplication gets reconciled on sight +- The ledger needs curation; entries with no recurrences eventually get folded into the general rules diff --git a/book/guidelines/writing-style.md b/book/guidelines/writing-style.md index 3f5b3df..1e55db6 100644 --- a/book/guidelines/writing-style.md +++ b/book/guidelines/writing-style.md @@ -6,7 +6,7 @@ description: Plain-language writing standard for every book document — fidelit Everything under `book/` (summary, changelog, learn, issue, task, plans, guidelines, docs) is written the same way: like a specific person speaking in a specific situation — not like a model performing writing. Professional is fine; templated is not. -The complete rule set lives in the shuorenhua skill (source: [MrGeDiao/shuorenhua](https://github.com/MrGeDiao/shuorenhua)). If it is installed in your environment, prefer it; this file is the project default and the fallback when it isn't. +Three layers carry this standard: the **`bowrite` skill**（薄写 — write thin, write well）is the executable form for agents, distilling [shuorenhua](https://github.com/MrGeDiao/shuorenhua) (source, MIT, by MrGeDiao) together with patterns accumulated in this project's own reviews; the upstream shuorenhua skill goes deepest for Chinese and is worth installing if available; this file is the in-project prose fallback when neither skill is loaded. ## Fidelity contract — above any style diff --git a/scripts/init-project.sh b/scripts/init-project.sh index 55c0ff1..87b5424 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 /" +echo " cp -r skills/bocode skills/feature-flow 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 30d4e2d..12339dd 100644 --- a/skills/README.md +++ b/skills/README.md @@ -1,25 +1,26 @@ # Skills -Three self-contained skills implement the BoCode workflow for AI agents. Each is a single `SKILL.md` in the standard format (frontmatter with `name` and `description`, then the body) — no code, no dependencies. +Four self-contained skills implement the BoCode workflow for AI agents. Each is a single `SKILL.md` in the standard format (frontmatter with `name` and `description`, then the body) — no code, no dependencies. | 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" | +| `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. ## Installation -Copy the three skill directories into your agent's skills folder: +Copy the four skill directories into your agent's skills folder: - **ZCode**: `~/.zcode/skills/` (user-wide) or `/.zcode/skills/` (per project) - **Claude Code**: `~/.claude/skills/` or `/.claude/skills/` - **Other SKILL.md-compatible agents**: the skills directory your tool documents ```bash -cp -r skills/bocode skills/feature-flow skills/book-writeback / +cp -r skills/bocode skills/feature-flow skills/book-writeback skills/bowrite / ``` -Optional, recommended for Chinese-writing teams: install [shuorenhua](https://github.com/MrGeDiao/shuorenhua) — the full plain-language ruleset that `book/guidelines/writing-style.md` distills and can act as a fallback for. +`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 f1be8a7..4291848 100644 --- a/skills/bocode/SKILL.md +++ b/skills/bocode/SKILL.md @@ -43,5 +43,5 @@ book/ - Don't edit `book/README.md` by hand — it's generated. - Don't archive by feature: `summary/`, `learn/`, `issue/`, `changelogs/` group by `YYYY-MM/` only; features are found through the index, frontmatter, and links. -- Don't write book documents in template-speak — follow `book/guidelines/writing-style.md` (plain language, facts locked). +- Don't write book documents in template-speak — write them thin and well (the **bowrite** skill, 薄写), per `book/guidelines/writing-style.md`: plain language, facts locked. - Don't treat a plan in `book/plans/` as a suggestion: it is the input to implementation, and deviations go back through design, not silently into code. diff --git a/skills/bowrite/SKILL.md b/skills/bowrite/SKILL.md new file mode 100644 index 0000000..9b947b5 --- /dev/null +++ b/skills/bowrite/SKILL.md @@ -0,0 +1,146 @@ +--- +name: bowrite +description: BoCode's writing skill (中文名：薄写) — write documents thin and well. Use when writing or revising any book document, README, summary, learn entry, issue, or changelog; when a draft smells like template-speak, translation-ese, or strained cleverness; and whenever text must shrink without losing substance. +--- + +# BoWrite（薄写） + +Write it thin. Write it well. + +把书读薄 is what a good reader does with a thick book. BoWrite does it at writing time: **把书写薄，把笔记写薄，把话说好——内容变少，核心没变。** + +Two mandates, always together: + +1. **Thin（写薄）**: fewer words, zero information lost. +2. **Well（写好）**: natural, direct, in the reader's language — never clever at the cost of clear. + +## The fidelity contract — before any thinning + +No rewrite may add facts, drop core facts, or change who is responsible. The following never move: + +- Numbers, versions, dates, commands, API names, parameter names, field names, config keys, logs, error messages +- Code blocks, table data, directory structures, links +- System-behavior subjects, domain terms, ADR conclusions, responsibility attribution +- Predicate strength: "improved performance" never softens to "touches performance"; `性能提升` never dilutes to `涉及性能` +- Ambiguous quantities stay as-is and get flagged, never "rounded" into new claims + +Thinning that loses facts isn't thinning — it's damage. + +## How to write it thin — the method + +把书读薄 is a reading craft: strip the book until its skeleton shows, then retell it with the book closed. Writing thin runs the same craft at writing time. Five moves, in order: + +### 1. 提骨架 — extract the skeleton + +State each paragraph's point in one sentence. Those sentences are the document's core; everything else is a cutting candidate. A paragraph whose point you can't state in one sentence doesn't know its own point yet — fix that before thinning. + +### 2. 逐句过刀 — the deletion test + +For every sentence ask: 删掉它，读者会少知道什么？"没什么" → cut. A concrete something → keep, then try to say it shorter. + +### 3. 合并同类 — keep the most specific + +The same point said twice — prose then summary, description then table — keeps only the more specific copy. A closing paragraph that merely restates what came before goes entirely. + +### 4. 修饰词折算 — modifiers pay rent + +Adjectives and adverbs convert into concrete facts or get cut: `非常快` → how fast; `很多问题` → how many, which ones; `进行了优化` → what changed, by how much. + +### 5. 复述检验 — the retell test + +Thin it, read it once, close it, retell the core. What you can retell is the core that survived; what you can't means you cut into it — put that back. **内容变少，核心没变——核心保没保住，复述说了算。** This is 把书读薄's own test, applied at writing time. + +### Worked example + +厚（62 字）： + +> 在进行文档迁移的过程当中，我们总共花费了大约三天左右的时间，对所有的旧文档进行了重新的整理和归类，最终的结果是全部的 120 篇文档都顺利地完成了迁移。 + +薄（19 字）： + +> 迁移花了三天，120 篇旧文档全部归位。 + +Same facts survive — 三天、全部、120 篇. What got cut is the rent-free padding: `进行`、`大约……左右`、`重新……整理`、`最终的`、`顺利地`. + +## Cut on sight + +- Filler openers, empty summaries, meta-commentary（`值得注意的是`、`综上所述`、"hope this helps"） +- Two sentences that say one thing become one +- Explain once — the first example or metaphor does the work, repeats go +- Intensifier clusters（`重要 / 关键 / 核心 / significant`）→ the concrete fact behind them +- Nominalized verbs（`进行 / 实现 / 完成` + 动名词）→ the action and its measure +- Long attributive chains → short subjects, direct verbs +- 二元对比骨架（`不是 X，而是 Y`）usually keeps only Y + +## How to write it well — the pattern ledger + +Real patterns caught in real reviews. This ledger is living: every new pattern found in review gets added here. + +### 1. Cleverness that makes the reader guess + +Metaphors read great to the writer and baffle the reader. If a figure of speech needs a beat of decoding, replace it with the plain statement. + +- ✗ 更新文档的好处在将来，跳过它的好处在眼前，所以文档**总输**。 +- ✓ ……跳过它马上就省事，所以文档**总是作用不大**。 +- ✗ 每次都**付全价**。 +- ✓ （删——事实句已经说清了，比喻没有增加信息） +- ✗ 不让你顺手修的**这道门，正是……的同一道门**。 +- ✓ 只记录、不修复，review 的结论才可信。 + +### 2. Over-compression + +Thin is not telegraphic. A sentence the reader can't decode on first pass carries zero information — compress words, not meaning. + +- ✗ 到最后没人信文档——**不信也对**。 +- ✓ 到最后没人信文档——过时的文档确实不值得信。 + +### 3. Emphasis formulas + +`不是 X，而是 Y` / `正是……的原因` / `同一个……` are scaffolding; the claim usually stands alone without the emphasis layer. + +- ✗ 这条规矩，**正是** review 能保持诚实**的原因**。 +- ✓ 只记录、不修复，review 的结论才可信。 + +### 4. Colloquial ↔ written boundary + +Spoken rhythm is welcome where it lands naturally（`越做越顺`、`踩坑`、`记一笔`、`顺手多做十二件`）；dialect and over-casual words get normalized in documents: + +- `根子` → `根源` · `漂` → `漂移` · `开发点什么` → `开始开发` + +### 5. Term discipline + +Don't borrow terms from other fields as ordinary words: + +- ✗ task notes are `工作记忆`（psychology's term for working memory） +- ✓ 任务跟踪 + +### 6. Translation-ese + +Multilingual documents are **re-expressed** in the target language, not translated sentence-by-sentence. Signals: long subjects, passive piles, `通过……来……`, English rhythm wearing Chinese words. + +- ✗ `可导航的真相`（calque of "navigable truth"） +- ✓ `能查的真相` + +### 7. Multilingual mirror blind spots + +Fixing a disease in one language leaves it alive in its translations — the same metaphors and compressions survive untouched because nobody looks at the siblings. When a fix lands in one language version, check the same sentences in the others. + +- Found: 中文版删掉的 `付全价` / `总输`，英文原版 "at full price" / "always loses" 原样健在——修 A 语言时必须回查同句的 B/C 语言。 + +### 8. Intro / first-point duplication + +An opening paragraph that previews the document often restates the first section in full — the same claim twice within one screen. Keep the hook in the intro; give the facts to the section that owns them. + +- Found: 引言说"每开一个新会话都从零开始"，问题 1 又说"每个会话从零开始"——引言留钩子，事实归问题 1。 + +## Read-back — three passes before done + +1. **Fidelity**: protected spans intact, no facts lost, terms stable, nothing reads broken after the cuts. +2. **Thinness**: what got removed — words, or information? Content shrinks, core doesn't. If the core shrank, put it back. +3. **Residue** (only if it still smells): openers, summary-closers, emphasis formulas, cleverness, over-even rhythm. + +The finish line is "ready to send" — not "sounds human". Stop there. + +## Standing on shuorenhua + +BoWrite distills [shuorenhua](https://github.com/MrGeDiao/shuorenhua)（MIT，by MrGeDiao）— the fuller plain-language ruleset, especially for Chinese — together with patterns accumulated in this project's own reviews. For deep Chinese cleanups the upstream skill goes further; `book/guidelines/writing-style.md` is the prose fallback inside every project. From f20b551329cc513b61ec6aa3720bf0d0f4bd7682 Mon Sep 17 00:00:00 2001 From: Focus Date: Mon, 14 Sep 2026 10:27:10 +0800 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=93=96=20docs:=20rewrite=20chinese=20?= =?UTF-8?q?readme=20and=20apply=20bowrite=20across=20all=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- README.ja.md | 18 +++++++-------- README.md | 22 +++++++++--------- README.zh-CN.md | 40 ++++++++++++++++----------------- book/docs/decisions/README.md | 2 +- book/guidelines/architecture.md | 2 +- book/guidelines/workflow.md | 2 +- skills/feature-flow/SKILL.md | 2 +- 8 files changed, 45 insertions(+), 45 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 47b46ae..e9e289b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ This file is the entry point for AI agents working on this repository. Humans: s -This project runs on the **BoCode workflow**: `code/` holds the source, `book/` holds the documentation stream and knowledge base. The highest architecture guidance lives inside the repository: long-term boundaries and hard constraints in `book/guidelines/architecture.md`, implementation snapshots in `book/docs/architecture/`. Internal documents never defer to external docs for authority. +This project runs on the **BoCode workflow**: `code/` holds the source, `book/` holds the documentation stream and knowledge base. The highest architecture guidance lives inside the repository: long-term boundaries and hard constraints in `book/guidelines/architecture.md`, implementation snapshots in `book/docs/architecture/`. ## Repository layout diff --git a/README.ja.md b/README.ja.md index 6371616..970ed0d 100644 --- a/README.ja.md +++ b/README.ja.md @@ -14,7 +14,7 @@ **ドキュメントがコードを駆動し、コードがドキュメントに書き戻す、プロジェクトテンプレート。** -BoCode はリポジトリに二つの半脳を与えます——ソースを置く `code/` と、ドキュメントの流れとナレッジベースを置く `book/` です。両者は双方向に接続されます。今のソフトウェアが実際に書かれている方法、つまり人間と AI コーディングエージェントの共同開発を前提に設計されています。エージェントは速いが状態を持たない。プロジェクトが複利的に成長するか、セッションごとにゼロリセットされるかは、知識が耐久性のある場所に置かれているかどうかで決まります。 +BoCode はリポジトリに二つの半脳を与えます——ソースを置く `code/` と、ドキュメントの流れとナレッジベースを置く `book/` です。両者は双方向に接続されます。今のソフトウェアが実際に書かれている方法、つまり人間と AI コーディングエージェントの共同開発を前提に設計されています。プロジェクトが複利的に成長するか、セッションごとにゼロリセットされるかは、知識が耐久性のある場所に置かれているかどうかで決まります。 ## 一行で導入 @@ -34,8 +34,8 @@ https://github.com/Focus695/BoCode を読み（まず ADOPT.md から）、そ AI エージェントで開発するプロジェクトは、ほぼ必ず三つの問題にぶつかります。 -1. **エージェントは状態を持たない。** セッションは毎回ゼロから始まります。書き残されていない知識は、再導出され、再質問され、再破壊されます——毎回定価を払いながら。 -2. **ドキュメントは腐る。** 立ち上げ時に一度書かれ、二度と更新されない。更新の利益は後で、スキップの利益は今なので、常に負けます。やがて誰も信じなくなり、当然です。 +1. **エージェントは状態を持たない。** セッションは毎回ゼロから始まります。書き残されていない知識は、再導出され、再質問され、再破壊されます。 +2. **ドキュメントは腐る。** 立ち上げ時に一度書かれ、二度と更新されない。更新の利益は後で、スキップの利益は今なので、更新は常に後回しにされます。やがて誰も信じなくなります——古いドキュメントは信じる価値がありません。 3. **人間がハンドルを失う。** エージェントは頼まれたものに加えて、頼まれていない十二個の変更も実装します。ゲートのないスピードは、スコープの漂移と意思決定の未記録と、「なぜ」の蒸発を意味します。 三つとも同じ根っこを指しています：知識と制御は、チャット履歴でも誰かの記憶でもない場所に住む必要がある、と。 @@ -117,7 +117,7 @@ diff を読まないと分からない summary は summary ではありません ### インデックス契約 -ナビゲートできないナレッジベースは、書き込み専用のディスクです。BoCode は発見可能性をビルドチェックにします： +見つけられないドキュメントは、存在しないのと同じです。BoCode は発見可能性をビルドチェックにします： - すべての book ドキュメントは frontmatter の `description` で始まる——体裁ではなく内容を語る、人の言葉で一行 - `code/tools/gen-book-index.mjs`（依存ゼロ、プレーン Node）が `book/README.md`——全ドキュメントのマスターインデックス——を再生成する @@ -127,7 +127,7 @@ diff を読まないと分からない summary は summary ではありません ### 人の言葉で書く -ドキュメントは何年も読まれ、数分で書かれる。だからスタイル規則は短く厳格です（`book/guidelines/writing-style.md`）：具体的な人が具体的な状況で話すように書く——プロフェッショナルで構わないが、テンプレート的なのは不可。埋め草の前置きと空っぽのまとめを削り、事実は固定する——数値・コマンド・名前・責任の所在は動かさない。中国語の完全なルールセットは [shuorenhua](https://github.com/MrGeDiao/shuorenhua) スキルに、guideline ファイルは言語非依存のデフォルトです。 +ドキュメントは何年も読まれ、数分で書かれる。だからスタイル規則は短く厳格です（`book/guidelines/writing-style.md`）：具体的な人が具体的な状況で話すように書く——プロフェッショナルで構わないが、テンプレート的なのは不可。埋め草の前置きと空っぽのまとめを削り、事実は固定する——数値・コマンド・名前・責任の所在は動かさない。この基準は `bowrite` スキル（薄写：薄く書く——文は減り、核は変わらない；うまく書く——自然に、直接に）がエージェント側で担い、MrGeDiao の [shuorenhua](https://github.com/MrGeDiao/shuorenhua) と本プロジェクトのレビューで蓄積したパターンから蒸留されています。 ### クリーンな git フロー @@ -149,8 +149,8 @@ git clone myproject && cd myproject # 2. テンプレートをあなたのプロジェクトに変える（名前、説明、記録のクリーンアップ）： bash scripts/init-project.sh myproject "What it does, in one line" -# 3. AI エージェントに三つのスキルをインストール： -cp -r skills/bocode skills/feature-flow skills/book-writeback / +# 3. AI エージェントに四つのスキルをインストール： +cp -r skills/bocode skills/feature-flow skills/book-writeback skills/bowrite / # (ZCode: ~/.zcode/skills/ · Claude Code: ~/.claude/skills/ — 詳細は skills/README.md) # 4. エージェントを AGENTS.md に向ける——ほとんどのツールが自動で読みます。 @@ -169,7 +169,7 @@ cp -r skills/bocode skills/feature-flow skills/book-writeback / | `book/plans/` | 実装プラン（施工図） | | `book/notes/{summary,learn,task,issue}/` | 四種類のノート | | `book/docs/{architecture,api,decisions}/` | スナップショット、契約、ADR | -| `skills/` | `bocode`、`feature-flow`、`book-writeback` | +| `skills/` | `bocode`、`feature-flow`、`book-writeback`、`bowrite` | | `code/tools/gen-book-index.mjs` | インデックスジェネレータ | | `scripts/init-project.sh` | テンプレート → あなたのプロジェクト | | `scripts/check-commit-message.mjs` | Clean Commit バリデータ（`.githooks/` 付き） | @@ -193,7 +193,7 @@ cp -r skills/bocode skills/feature-flow skills/book-writeback / ## クレジット -BoCode の git 規律は WGTech Labs の二つのオープンスタンダード——[Clean Commit](https://github.com/wgtechlabs/clean-commit)（コミットメッセージ形式）と [Clean Flow](https://github.com/wgtechlabs/clean-flow)（ブランチモデル）——の上に構築され、両スペックが記述するが同梱しない実行ツールを追加しています。人の言葉で書くスタイルは MrGeDiao の [shuorenhua](https://github.com/MrGeDiao/shuorenhua) に由来します。 +BoCode の git 規律は WGTech Labs の二つのオープンスタンダード——[Clean Commit](https://github.com/wgtechlabs/clean-commit)（コミットメッセージ形式）と [Clean Flow](https://github.com/wgtechlabs/clean-flow)（ブランチモデル）——の上に構築され、両スペックが記述するが同梱しない実行ツールを追加しています。人の言葉で書くスタイルは MrGeDiao の [shuorenhua](https://github.com/MrGeDiao/shuorenhua) に由来し、`bowrite` スキルへ蒸留されています。 ## ライセンス diff --git a/README.md b/README.md index c005282..dafc05d 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ **A project template where documentation drives code, and code writes back.** -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 actually written now: by a human and AI coding agents together, where agents are fast but stateless, and the difference between a project that compounds and one that resets every session is whether its knowledge lives somewhere durable. +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. ## Adopt it in one line @@ -26,7 +26,7 @@ Read https://github.com/Focus695/BoCode — start with ADOPT.md — and retrofit Starting from scratch? The three-command Quick Start is below. -Clone it, run one script, install three 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. +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,8 +36,8 @@ Clone it, run one script, install three skills, and your project gains: a gated 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 — at full price, every time. -2. **Documentation rots.** Written once at the start, updated never. Because updating it pays off later and skipping it pays off now, it always loses. Eventually nobody trusts it, and reasonably so. +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. +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. @@ -102,7 +102,7 @@ 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 design intent: agents compress implementation to minutes, which moves the bottleneck to decisions and scope. The gates put human hands 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.** The gate that didn't let you fix it in passing is the same gate that keeps the review honest. +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 @@ -119,7 +119,7 @@ A summary that requires reading the diff isn't a summary. A learn entry whose ti ### The index contract -A knowledge base you can't navigate is a write-only disk. BoCode makes discoverability a build check: +Documentation you can't find doesn't exist. BoCode makes discoverability a build check: - Every book document starts with a frontmatter `description` — one plain-language line about the *content*, not the genre. - `code/tools/gen-book-index.mjs` (zero dependencies, plain Node) regenerates `book/README.md` — the master index of every document, grouped by directory. @@ -129,7 +129,7 @@ A knowledge base you can't navigate is a write-only disk. BoCode makes discovera ### 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. For Chinese writing, the full ruleset is the [shuorenhua](https://github.com/MrGeDiao/shuorenhua) skill; the guideline file is the language-agnostic default. +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. ### Clean git flow @@ -151,8 +151,8 @@ git clone myproject && cd myproject # 2. Turn the template into your project (name, description, clean records): bash scripts/init-project.sh myproject "What it does, in one line" -# 3. Install the three skills for your AI agent: -cp -r skills/bocode skills/feature-flow skills/book-writeback / +# 3. Install the four skills for your AI agent: +cp -r skills/bocode skills/feature-flow 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 +171,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` | +| `skills/` | `bocode`, `feature-flow`, `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/`) | @@ -195,7 +195,7 @@ Months are stable, low-maintenance physical grouping. Features are found through ## Credits -BoCode's git discipline builds on two open standards by WGTech Labs — [Clean Commit](https://github.com/wgtechlabs/clean-commit) (commit message format) and [Clean Flow](https://github.com/wgtechlabs/clean-flow) (branching model) — and adds the enforcement tooling both specs describe but don't ship. The plain-language writing standard draws on [shuorenhua](https://github.com/MrGeDiao/shuorenhua) by MrGeDiao. +BoCode's git discipline builds on two open standards by WGTech Labs — [Clean Commit](https://github.com/wgtechlabs/clean-commit) (commit message format) and [Clean Flow](https://github.com/wgtechlabs/clean-flow) (branching model) — and adds the enforcement tooling both specs describe but don't ship. The plain-language writing standard draws on [shuorenhua](https://github.com/MrGeDiao/shuorenhua) by MrGeDiao, distilled into the `bowrite` skill. ## License diff --git a/README.zh-CN.md b/README.zh-CN.md index c42a5e1..2401325 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -14,7 +14,7 @@ **让文档驱动代码，让代码反过来写文档。** -BoCode 把仓库分成两半：`code/` 放源代码，`book/` 放文档和知识库，两边互相驱动。它针对的场景很具体：现在大部分代码是人和 AI agent 一起写的。agent 快，但每开一个新会话就从零开始——项目知识有没有存在一个可靠的地方，决定了开发是越滚越顺，还是每轮都重付学费。 +BoCode 把仓库分成两半：`code/` 放源代码，`book/` 放文档和知识库，两边互相驱动。它是为现在最常见的开发方式设计的：人和 AI agent 一起写代码。agent 快，但没有记忆。项目知识存在哪里，决定了开发是越做越顺，还是每个会话都重新踩一遍坑。 ## 一句话接入 @@ -34,15 +34,15 @@ BoCode 把仓库分成两半：`code/` 放源代码，`book/` 放文档和知识 用 AI agent 写代码的项目，几乎都会撞上三件事： -1. **Agent 没有记忆。** 每个会话从零开始。没写下来的知识会被重新推导一遍、重新问一遍、重新踩一遍——每次都付全价。 -2. **文档会烂。** 立项时写一次，之后没人更新。更新文档的好处在将来，跳过它的好处在眼前，所以文档总输。到最后没人信文档——不信也对。 -3. **人抓不住方向盘。** 你让 agent 做一件事，它会顺手多做十二件。速度上去了、关卡没跟上，作用域就开始漂：改了不该改的，决定了没人知道的，半年后没人说得清"当时为什么这么做"。 +1. **Agent 没有记忆。** 每个会话从零开始。没写下来的知识，每个会话都要重新推导一遍、重新问一遍、重新踩一遍坑。 +2. **文档会过时。** 立项时写一次，之后没人更新。更新文档的好处要很久之后才看得到，跳过它马上就省事，所以文档总是作用不大。到最后没人信文档——过时的文档确实不值得信。 +3. **人抓不住方向盘。** 你让 agent 做一件事，它会顺手多做十二件。速度上去了、关卡没跟上，作用域就开始漂移：改了不该改的，做了没人知道的决定，半年后没人说得清"当时为什么这么做"。 -三件事的根子是同一个：知识不能只活在聊天记录和人脑里。 +三件事的根源是同一个：知识不能只存在聊天记录和人脑里。 ### 两个半脑 -BoCode 的答案是结构。一个项目有两半： +BoCode 用结构回答这个问题。一个项目有两半： - **`code/`** 回答"它现在是怎么跑的" - **`book/`** 回答"它为什么长这样、做过什么决定、踩过什么坑" @@ -80,7 +80,7 @@ BoCode 的答案是结构。一个项目有两半： **code → book**：活干完后回写——summary 写给不看 diff 的人，learn 存给下个会话检索，issue 记下发现但先不修的问题，changelog 记一笔，索引刷一遍。 -这就是飞轮：每转一圈，book 都比上一圈更全；每个会话——不管是人还是 agent，今天还是一年后——都站在全部既有经验上开工。**book 越全，对下一个接手的人越值钱。** 开发变成复利，不用每次从零再来。 +这就是飞轮：每转一圈，book 都比上一圈更全；不管对人还是 agent，今天还是一年后，每个会话都从积累好的经验开始。**book 越全，对下一个接手的人越值钱。** 开发变成复利，不用每次从零再来。 --- @@ -100,20 +100,20 @@ BoCode 的答案是结构。一个项目有两半： | 5 Review | 问题清单 | 只记录，不修复 | | 6 收尾 | summary、learn、issue、changelog、索引 | 只记录，不修复 | -设计意图：agent 把实现压到分钟级，瓶颈就挪到了决策和作用域上。关卡把人的手正好放在那里——Step 0 补上需求没说的话，Phase 2 由人拍板方向，Phase 5/6 把"看"和"改"分开。**Review 时发现的问题进清单，修复是另一件事。** 不让你顺手修的这道门，正是让 review 保持诚实的同一道门。 +设计意图：agent 把实现压到分钟级，瓶颈就挪到了决策和作用域上，关卡恰好守在那里——Step 0 补上需求没说的话，Phase 2 由人拍板方向，Phase 5/6 把"看"和"改"分开。**Review 时发现的问题进清单，修复是另一件事。** 只记录、不修复，review 的结论才可信。 ### 为读者而写 -book 的文档按读者分流，不按产物类型（`book/notes/`）： +book 的文档按读者分流，而不是按文档类型（`book/notes/`）： | 类型 | 写给谁 | 形态 | |------|--------|------| | `summary/` | 人类为主 | 报告：背景 → 做了什么 → 为什么 → 效果 | | `learn/` | 人类 + agent | 可检索的知识条目，带 tags——包括症状词（"timeout"、"drift"） | | `issue/` | 人类 + agent | 问题 + 复现 + 建议方向 | -| `task/` | 工作记忆 | 检查清单 | +| `task/` | 任务跟踪 | 检查清单 | -要读 diff 才懂的 summary 不是 summary；标题答不了问题的 learn，下个会话也搜不到。`book/notes/README.md` 里的模板就是质量线。 +要读 diff 才懂的 summary 不是 summary；标题答不了问题的 learn，下个会话也搜不到。`book/notes/README.md` 里的模板就是合格线。 ### 索引契约 @@ -127,7 +127,7 @@ book 的文档按读者分流，不按产物类型（`book/notes/`）： ### 说人话 -文档是几分钟写完、要被读好几年的东西，所以风格规则短而严（`book/guidelines/writing-style.md`）：像具体的人在具体场景里说话——专业没关系，模板腔不行。套话和空总结删掉，事实锁死：数字、命令、名称、责任主体一个不动。中文的完整规则在 [shuorenhua](https://github.com/MrGeDiao/shuorenhua) skill；guideline 文件是跨语言的默认兜底。 +文档是几分钟写完、要被读好几年的东西，所以风格规则短而严（`book/guidelines/writing-style.md`）：像具体的人在具体场景里说话——专业可以，模板化不行。套话和空总结删掉，事实锁死：数字、命令、名称、责任主体一个不动。这套标准由 `bowrite` skill（薄写：写薄——内容变少、核心不变；写好——自然、直接、不抖机灵）在 agent 侧执行，它蒸馏自 MrGeDiao 的 [shuorenhua](https://github.com/MrGeDiao/shuorenhua)，加上本项目 review 中攒下的表达模式。 ### 干净的 git 流 @@ -135,7 +135,7 @@ git 历史也是 book 的一部分（`book/guidelines/git-workflow.md`）。非 ### 用自己建的，干干净净交付 -BoCode 是自己的第一个用户：奠基走完了结构化需求、经确认的设计、分阶段施工和逐步验证，提交历史全程 Clean Commit——整个过程在 git log 里可查。你拿到的模板是干净的：没有带日期的记录、没有别人的 plan，book 是空的，等着写你的。只留一个示范：[ADR-001](book/docs/decisions/ADR-001-adopt-bocode.md)——"采用这套工作流"的决策记录，你的项目会第一个重申它。 +BoCode 是自己的第一个用户：它的奠基就是按这套流程走的——结构化需求、设计确认、分阶段施工、逐步验证，提交历史全程 Clean Commit，整个过程在 git log 里可查。你拿到的模板是干净的：没有带日期的记录、没有别人的 plan，book 是空的，等着写你的。只留一个示范：[ADR-001](book/docs/decisions/ADR-001-adopt-bocode.md)——"采用这套工作流"的决策记录，这也是你的项目开工后要写的第一个决定。 --- @@ -149,15 +149,15 @@ git clone myproject && cd myproject # 2. 把模板变成你的项目（起名、填描述、清掉模板记录）： bash scripts/init-project.sh myproject "一句话说明它是干什么的" -# 3. 给你的 AI agent 装上三个 skill： -cp -r skills/bocode skills/feature-flow skills/book-writeback / +# 3. 给你的 AI agent 装上四个 skill： +cp -r skills/bocode skills/feature-flow skills/book-writeback skills/bowrite / # （ZCode: ~/.zcode/skills/ · Claude Code: ~/.claude/skills/ —— 见 skills/README.md） # 4. 让 agent 指向 AGENTS.md——多数工具会自动读。 -# 然后开发点什么，skill 会带着流程走。 +# 然后开始开发，skill 会带着流程走。 ``` -需要的只有 `bash` 和 `node`（跑两个脚本用）。不装包、没有 install 步骤、没有 lockfile——工具链故意做得无聊。 +需要的只有 `bash` 和 `node`（跑两个脚本用）。不装包、没有 install 步骤、没有 lockfile——工具链刻意保持朴素。 ## 仓库导览 @@ -169,7 +169,7 @@ cp -r skills/bocode skills/feature-flow skills/book-writeback / | `book/plans/` | 实现计划（施工图） | | `book/notes/{summary,learn,task,issue}/` | 四类笔记 | | `book/docs/{architecture,api,decisions}/` | 快照、契约、ADR | -| `skills/` | `bocode`、`feature-flow`、`book-writeback` | +| `skills/` | `bocode`、`feature-flow`、`book-writeback`、`bowrite` | | `code/tools/gen-book-index.mjs` | 索引生成器 | | `scripts/init-project.sh` | 模板 → 你的项目 | | `scripts/check-commit-message.mjs` | Clean Commit 校验器（含 `.githooks/`） | @@ -186,14 +186,14 @@ cp -r skills/bocode skills/feature-flow skills/book-writeback / 只要读 `AGENTS.md`、认 `SKILL.md` 格式就行（ZCode、Claude Code 和兼容工具）。没装 skill 也能跑：guidelines 用文字载着同样的规则。 **不刷索引会怎么样？** -运行不会坏——但索引一过期，整套体系靠的可发现性就开始漏。所以检查让缺 description 的文档直接报错，而不是悄悄放过去。 +运行不会出问题——但索引一过期，文档就慢慢找不到了，而这套体系靠的正是"找得到"。所以检查让缺 description 的文档直接报错，而不是悄悄放过去。 **为什么按 `YYYY-MM/` 归档，不按功能建目录？** 月份是稳定的物理分组，维护成本最低。功能靠索引、frontmatter 和链接来找——不靠把跨月的功能切碎在目录树里。 ## 致谢 -BoCode 的 git 纪律构建在 WGTech Labs 的两个开放标准上——[Clean Commit](https://github.com/wgtechlabs/clean-commit)（提交格式）与 [Clean Flow](https://github.com/wgtechlabs/clean-flow)（分支模型）——并为这两个"只有规范没有工具"的标准补上了执行工具链。说人话书写规范源自 MrGeDiao 的 [shuorenhua](https://github.com/MrGeDiao/shuorenhua)。 +BoCode 的 git 纪律构建在 WGTech Labs 的两个开放标准上——[Clean Commit](https://github.com/wgtechlabs/clean-commit)（提交格式）与 [Clean Flow](https://github.com/wgtechlabs/clean-flow)（分支模型）——并为这两个"只有规范没有工具"的标准补上了执行工具链。说人话书写规范源自 MrGeDiao 的 [shuorenhua](https://github.com/MrGeDiao/shuorenhua)，蒸馏成了 `bowrite` skill。 ## 许可 diff --git a/book/docs/decisions/README.md b/book/docs/decisions/README.md index aeda428..e2dc5cc 100644 --- a/book/docs/decisions/README.md +++ b/book/docs/decisions/README.md @@ -4,7 +4,7 @@ description: How to write an ADR here — sections, naming, numbering, and when # Decisions (ADR) -An architecture decision record answers one question: why this choice. Future readers — humans and agents — will ask "why is it like this"; the ADR is the answer they find. +An architecture decision record answers the question future readers — humans and agents — will ask: why is it like this. ## When to write one diff --git a/book/guidelines/architecture.md b/book/guidelines/architecture.md index 6f52d09..b698faa 100644 --- a/book/guidelines/architecture.md +++ b/book/guidelines/architecture.md @@ -23,7 +23,7 @@ A boundary rule names two concerns and keeps them apart, with the reason a revie | Raw Data ≠ Derived View | Raw inputs and computed views have different lifecycles and different owners; fusing them couples ingestion to presentation | | Primary DB ≠ Cache | A cache may speed things up but never own truth; everything in it must be rebuildable | -Write rules you can enforce in review. If a rule can't be checked against a diff, it's a wish, not a boundary. +Write rules you can enforce in review. If a rule can't be checked against a diff, it's a wish. ## Maintenance diff --git a/book/guidelines/workflow.md b/book/guidelines/workflow.md index aa05bc2..e3a09d4 100644 --- a/book/guidelines/workflow.md +++ b/book/guidelines/workflow.md @@ -18,7 +18,7 @@ Every feature moves through these phases in order. **No skipping.** | Phase 5 | Code review | Review findings | Record only — no fixes | | Phase 6 | Wrap-up | Docs, learnings, issues | Record only — no fixes | -Step 0 comes before any code. Fill the brief: background, scope (what it affects, what it explicitly does **not** affect, and the boundaries), and the requirement itself. An empty "does not affect" list is the number-one cause of out-of-scope changes in Phase 3 — it is a required slot, not an optional one. +Step 0 comes before any code. Fill the brief: background, scope (what it affects, what it explicitly does **not** affect, and the boundaries), and the requirement itself. An empty "does not affect" list is the number-one cause of out-of-scope changes in Phase 3 — the exclusions slot is required. Phase 4 runs test-first: write a failing test, write the minimum implementation that passes it, refactor with the test staying green. Coverage must include the normal path, boundary inputs (ranges, empty, extremes), error paths, and a regression check that existing behavior didn't break. diff --git a/skills/feature-flow/SKILL.md b/skills/feature-flow/SKILL.md index cad160c..c2e58d4 100644 --- a/skills/feature-flow/SKILL.md +++ b/skills/feature-flow/SKILL.md @@ -17,7 +17,7 @@ Render the brief below and fill every slot. For empty slots you have two duties: **A. Missing → ask.** Real gaps go to the user as questions. Don't guess background or scope — they change what gets built. Ask once, completely. -**B. Sufficient → recommend.** Once enough is known to start, don't stop — raise the design axes the user didn't mention (permissions, notifications, idempotency, caching, transactions, boundaries, regression, generated-artifact sync…). Mark each as `[recommended — confirm or reject]`. This is the core increment of this skill: filling gaps the user didn't know were there. +**B. Sufficient → recommend.** Once enough is known to start, don't stop — raise the design axes the user didn't mention (permissions, notifications, idempotency, caching, transactions, boundaries, regression, generated-artifact sync…). Mark each as `[recommended — confirm or reject]`. Fill the gaps the user didn't know were there. ### Brief template