diff --git a/README.md b/README.md index 175e300..aaf9fec 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ It combines shared config packages, repository templates, and a CLI so teams can Product documentation lives in `docs/` and is published as a VitePress site in English and Japanese. - overview: `docs/index.md` +- adoption playbook: `docs/adoption-playbook.md` - concepts and safety model: `docs/concepts.md` - CLI usage: `docs/cli.md` - base preset details: `docs/templates/base.md` diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index bb90c8f..96179f9 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -7,6 +7,7 @@ const base = const englishNav = [ { text: "Overview", link: "/" }, { text: "Concepts", link: "/concepts" }, + { text: "Adoption", link: "/adoption-playbook" }, { text: "CLI", link: "/cli" }, { text: "Base Template", link: "/templates/base" }, ]; @@ -17,6 +18,7 @@ const englishSidebar = [ items: [ { text: "Overview", link: "/" }, { text: "Concepts", link: "/concepts" }, + { text: "Adoption Playbook", link: "/adoption-playbook" }, { text: "CLI", link: "/cli" }, { text: "Base Template", link: "/templates/base" }, ], @@ -26,6 +28,7 @@ const englishSidebar = [ const japaneseNav = [ { text: "概要", link: "/ja/" }, { text: "基本概念", link: "/ja/concepts" }, + { text: "導入", link: "/ja/adoption-playbook" }, { text: "CLI", link: "/ja/cli" }, { text: "Base Template", link: "/ja/templates/base" }, ]; @@ -36,6 +39,7 @@ const japaneseSidebar = [ items: [ { text: "概要", link: "/ja/" }, { text: "基本概念", link: "/ja/concepts" }, + { text: "導入プレイブック", link: "/ja/adoption-playbook" }, { text: "CLI", link: "/ja/cli" }, { text: "Base Template", link: "/ja/templates/base" }, ], diff --git a/docs/adoption-playbook.md b/docs/adoption-playbook.md new file mode 100644 index 0000000..f846080 --- /dev/null +++ b/docs/adoption-playbook.md @@ -0,0 +1,98 @@ +# Adoption Playbook + +This page explains how to roll out shared repository standards into real repositories without creating a large, risky migration. + +## Why standards rollouts usually fail + +Many standards projects fail for one of these reasons: + +- they try to replace too many files at once +- they assume all target repositories are greenfield +- they hide the real diff behind generators +- they require teams to trust a tool before they can review the change + +Those problems get worse in AI-assisted repositories, where multiple tools, prompts, and local conventions evolve quickly. + +## The design goal + +`project-standards` is intentionally shaped around a small, reviewable adoption path: + +- preview the exact diff first +- keep writes explicit +- avoid clobbering repository-specific files +- separate shared config from in-repo templates +- make future upgrades possible without forcing full replacement + +## The rollout strategy + +### 1. Start with `diff` + +The first step for an existing repository should always be a read-only preview: + +```sh +node packages/cli/dist/index.js diff ../target-repository +``` + +This keeps the review conversation grounded in the actual change instead of an abstract promise. + +### 2. Prefer `--dry-run` before real writes + +If the diff looks reasonable, the next step is still a non-destructive dry run: + +```sh +node packages/cli/dist/index.js apply ../target-repository --include quality --dry-run +``` + +That extra step matters when the target repository is active and has local conventions that the base preset should not silently overwrite. + +### 3. Use file strategies that respect reality + +The current MVP intentionally keeps the strategy surface small: + +- `create_if_missing` +- `replace_if_managed` + +This avoids pretending that partial ownership is easy. A repository either opts into a managed file or keeps its local version. + +### 4. Keep shared config and templates separate + +Two kinds of standards should not be treated the same: + +- shared config packages are better referenced than copied +- repository-local files still need templates and explicit ownership rules + +That separation makes it easier to update behavior later without hiding the source of truth. + +## Why this works well for AI-assisted repositories + +AI-assisted development increases the number of generated docs, prompts, rules, and local workflow files. That makes accidental drift more likely. + +A useful standards tool in that environment should: + +- show the diff before writing +- keep managed boundaries obvious +- avoid destructive upgrades by default +- make quality-related adoption small enough for normal review + +`project-standards` is designed around those constraints instead of treating them as edge cases. + +## A practical rollout order + +For an existing repository, a safe sequence usually looks like this: + +1. inspect the current repository and decide what should remain local +2. run `diff` +3. apply only the quality-related subset with `--dry-run` +4. review the result with the team +5. run the real apply once the managed boundaries are accepted +6. leave stack-specific follow-ups for separate PRs + +## What this page should signal + +This repository is not just a config dump. It is an attempt to make repository standards adoptable in the messy conditions where teams actually work: + +- existing repositories +- multiple tools +- AI-assisted workflows +- partial ownership +- review-first engineering culture diff --git a/docs/index.md b/docs/index.md index 95fa698..00723a0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -21,6 +21,7 @@ It combines shared config packages, repository templates, and a CLI so teams can ## Read next - [Concepts](./concepts.md) +- [Adoption Playbook](./adoption-playbook.md) - [CLI](./cli.md) - [Base Template](./templates/base.md) diff --git a/docs/ja/adoption-playbook.md b/docs/ja/adoption-playbook.md new file mode 100644 index 0000000..18f4ec8 --- /dev/null +++ b/docs/ja/adoption-playbook.md @@ -0,0 +1,92 @@ +# 導入プレイブック + +このページでは、共有リポジトリ標準を大きくて危険な migration にせず、既存リポジトリへ小さく導入する考え方を整理します。 + +## なぜ標準導入は失敗しやすいのか + +標準導入がうまくいかない理由は、だいたい次のどれかです。 + +- 一度に置き換えるファイルが多すぎる +- 対象リポジトリが greenfield だと暗黙に仮定している +- generator の裏に実際の差分が隠れている +- review より先にツールへの信頼を要求してしまう + +この問題は、AI 支援開発の repo でさらに大きくなります。prompt、rule、agent guide、local workflow が増えるほど、repo ごとの差異や drift は起きやすくなるからです。 + +## 設計目標 + +`project-standards` は、既存 repo にも導入できるよう、次の方針で設計しています。 + +- まず実差分を `diff` で見る +- write を明示的にする +- repo 固有ファイルをむやみに上書きしない +- shared config と template の責務を分ける +- 将来の upgrade を見据えつつ、最初の導入は小さく保つ + +## 導入戦略 + +### 1. 既存 repo では `diff` から始める + +最初の一手は常に read-only preview です。 + +```sh +node packages/cli/dist/index.js diff ../target-repository +``` + +まず実差分を見せることで、「何が変わるのか分からないまま apply する」状態を避けます。 + +### 2. 実 apply の前に `--dry-run` を挟む + +差分が妥当でも、次の一手はまだ non-destructive であるべきです。 + +```sh +node packages/cli/dist/index.js apply ../target-repository --include quality --dry-run +``` + +対象 repo が既に運用中で、局所的な慣習や管理境界を持っているときほど、この一段が効きます。 + +### 3. 現実に合わせた file strategy を使う + +MVP では strategy をあえて絞っています。 + +- `create_if_missing` +- `replace_if_managed` + +partial ownership を簡単に扱えるふりをせず、「そのファイルを managed として引き受けるか、ローカル管理のままにするか」をはっきりさせるためです。 + +### 4. shared config と template を分ける + +repo 標準には、同じように見えて性質が違うものが混ざります。 + +- shared config package として参照したいもの +- repo 内に実ファイルとして存在してほしい template + +この 2 つを分けることで、後から挙動を更新しやすくしつつ、正本の位置も分かりやすくできます。 + +## AI 支援開発の repo で効く理由 + +AI 支援開発では、doc、prompt、rule、command、local workflow file が増えやすく、repo drift が起きやすくなります。 + +その環境で役に立つ標準導入ツールは、少なくとも次を満たす必要があります。 + +- write 前に実差分を見せる +- managed boundary を明確にする +- destructive upgrade を default にしない +- quality 系の導入を通常の review で見切れる大きさに保つ + +`project-standards` は、これらを後付けの例外ではなく、最初から前提条件として扱っています。 + +## 実際の導入順 + +既存 repo に入れるときの安全な順番は、だいたい次のとおりです。 + +1. 現在の repo を見て、ローカルに残すものを決める +2. `diff` を取る +3. quality 系だけ `--dry-run` で当てる +4. team で review する +5. managed boundary に合意できたら real apply を実行する +6. stack 固有の follow-up は別 PR に分ける + +## このページで伝えたいこと + +この repo は単なる設定配布ではありません。既存 repo、複数ツール、AI 支援開発、partial ownership という現実の条件下で、標準導入を review-first に成立させるための platform として設計しています。 diff --git a/docs/ja/index.md b/docs/ja/index.md index cd98466..456d806 100644 --- a/docs/ja/index.md +++ b/docs/ja/index.md @@ -21,6 +21,7 @@ shared config package、repository template、CLI を 1 か所にまとめるこ ## 次に読む - [基本概念](./concepts.md) +- [導入プレイブック](./adoption-playbook.md) - [CLI](./cli.md) - [Base Template](./templates/base.md)