create-ai-project 1.20.2 → 1.20.3

package/README.ja.md

@@ -19,15 +19,16 @@
 1. [クイックスタート（3ステップ）](#-クイックスタート3ステップ)
 2. [既存プロジェクトの更新](#-既存プロジェクトの更新)
 3. [Vibe Codingの先へ：なぜサブエージェント？](#-vibe-codingの先へなぜサブエージェント)
-4. [スキルシステム](#-スキルシステム)
-5. [このボイラープレートで作られたプロジェクト](#-このボイラープレートで作られたプロジェクト)
-6. [ドキュメント＆ガイド](#-ドキュメントガイド)
-7. [スラッシュコマンド](#-スラッシュコマンド)
-8. [開発ワークフロー](#-claude-code-ワークフロー)
-9. [プロジェクト構成](#-プロジェクト構成)
-10. [パッケージマネージャーの設定](#-パッケージマネージャーの設定)
-11. [多言語対応](#-多言語対応)
-12. [よくある質問](#-よくある質問)
+4. [スラッシュコマンド](#-スラッシュコマンド)
+5. [スキルのカスタマイズ](#-スキルのカスタマイズ)
+6. [スキルシステム](#-スキルシステム)
+7. [このボイラープレートで作られたプロジェクト](#-このボイラープレートで作られたプロジェクト)
+8. [ドキュメント＆ガイド](#-ドキュメントガイド)
+9. [開発ワークフロー](#-claude-code-ワークフロー)
+10. [プロジェクト構成](#-プロジェクト構成)
+11. [パッケージマネージャーの設定](#-パッケージマネージャーの設定)
+12. [多言語対応](#-多言語対応)
+13. [よくある質問](#-よくある質問)
 
 ## ⚡ クイックスタート（3ステップ）
 
@@ -102,7 +103,7 @@ ignoreされたファイルは更新時に保護されます。ただし、ignor
 
 ## 🚀 Vibe Codingの先へ：なぜサブエージェント？
 
-Vibe Codingの先へ — **Agentic Coding**（構造化されたワークフローを専門AIエージェントに委任するアプローチ）がプロフェッショナルな開発の標準になりつつあります。このボイラープレートはClaude Codeのサブエージェントでそれを実現します。
+Vibe Codingの先へ — **Agentic Coding**（構造化されたワークフローを専門AIエージェントに委任するアプローチ）が実践的な開発手法として広がりつつあります。このボイラープレートはClaude Codeのサブエージェントでそれを実現します。
 
 **従来のAIコーディングの問題**
 - ❌ 長時間のセッションでコンテキストを失う
@@ -112,7 +113,7 @@ Vibe Codingの先へ — **Agentic Coding**（構造化されたワークフロ
 **サブエージェントによるContext Engineering**
 - ✅ 専門的な単一の役割に分割（設計、実装、レビュー）
 - ✅ 各エージェントが新鮮で集中したコンテキストを持つ — 枯渇なし
-- ✅ 品質低下なしで規模感のあるタスクを処理
+- ✅ 大規模なプロジェクトでも品質低下なしに処理
 
 これはClaude Codeのサブエージェント機構が、各エージェントを独立したコンテキストウィンドウで実行する仕組みに基づいています。親セッションがタスクを委任し、各サブエージェントはクリーンで集中したコンテキストで処理を開始します。品質チェック（lint、型チェック、テスト、ビルド）はCIではなくコミット前にローカルで実行されるため、フィードバックループが速く、pushする時点でコードは検証済みです。
 
@@ -124,6 +125,45 @@ Vibe Codingの先へ — **Agentic Coding**（構造化されたワークフロ
 
 *サブエージェントが連携してTypeScriptプロジェクトを構築する様子*
 
+## 📝 スラッシュコマンド
+
+Claude Codeで利用できる主要なコマンド
+
+| コマンド | 目的 | 使用場面 |
+|---------|------|----------|
+| `/implement` | 要件から実装までの一貫した開発 | 新機能開発 |
+| `/task` | スキルに基づいた単一タスクの実行 | バグ修正、小規模な変更 |
+| `/design` | 設計書の作成 | アーキテクチャの計画時 |
+| `/plan` | 設計書から作業計画書を作成 | 設計承認後 |
+| `/build` | 既存の計画から実行 | 作業の再開時 |
+| `/review` | コードの準拠性確認 | 実装完了後 |
+| `/diagnose` | 根本原因分析ワークフロー | デバッグ、トラブルシューティング |
+| `/reverse-engineer` | コードからPRD/Design Docを生成 | 既存システムのドキュメント化 |
+| `/create-skill` | 対話形式で新しいスキルを作成 | プロジェクト固有のルールを追加 |
+| `/refine-skill` | 品質レビュー付きでスキルを修正 | スキルの精度改善 |
+
+フロントエンド用（`/front-design`（UI Spec + Design Doc）, `/front-build`, `/front-review`, `/front-plan`）やユーティリティコマンド（`/add-integration-tests`, `/update-doc`）も利用できます。
+
+[コマンドの詳細はこちら →](docs/guides/ja/use-cases.md)
+
+## 🌱 スキルのカスタマイズ
+
+このボイラープレートには汎用的なスキルが同梱されており、すぐに使い始められます。ただし、スキルが本領を発揮するのは、プロジェクト固有のコーディング規約やドメイン制約、チームの意思決定を反映させたときです。
+
+同梱されているスキルはベースラインです。次のステップは、それをあなたのプロジェクトに合わせて育てていくことです。
+
+- **`/project-inject`** — プロジェクトの前提情報を設定（初回実行、毎セッション参照）
+- **`/create-skill`** — 対話形式で新しいスキルを作成
+- **`/refine-skill`** — 既存スキルを品質レビュー付きで改善
+
+スキル作成の原則やベストプラクティスは[スキル編集ガイド](docs/guides/ja/skills-editing-guide.md)を参照してください。
+
+### スキルの効果検証
+
+スキルを作ることと、それが実際にエージェントの挙動を改善しているかを知ることは別の問題です。スキルは互いに影響し合い、プロジェクトのコンテキストとも相互作用するため、確実に効果を知るには実際に動かして比較するしかありません。
+
+[rashomon](https://github.com/shinpr/rashomon)はこのためのClaude Codeプラグインです。スキル変更が本当に改善につながったのか、感覚ではなくエビデンスで確認したいときに使えます。
+
 ## 🎨 スキルシステム
 
 このボイラープレートでは、自律的（Agentic）な実装ワークフローで用いられている原理原則を、日常のタスクにおいても必要に応じて参照できるようスキルとして提供しています。
@@ -171,25 +211,6 @@ Vibe Codingの先へ — **Agentic Coding**（構造化されたワークフロ
 - **[スキル編集ガイド](docs/guides/ja/skills-editing-guide.md)** - ライブラリドキュメント、チームルール、プロジェクト固有の知識をAIに追加
 - **[設計思想](https://qiita.com/shinpr/items/98771c2b8d2e15cafcd5)** - このアプローチがなぜ有効か
 
-## 📝 スラッシュコマンド
-
-Claude Codeで利用できる主要なコマンド
-
-| コマンド | 目的 | 使用場面 |
-|---------|------|----------|
-| `/implement` | 要件から実装までの一貫した開発 | 新機能開発 |
-| `/task` | スキルに基づいた単一タスクの実行 | バグ修正、小規模な変更 |
-| `/design` | 設計書の作成 | アーキテクチャの計画時 |
-| `/plan` | 設計書から作業計画書を作成 | 設計承認後 |
-| `/build` | 既存の計画から実行 | 作業の再開時 |
-| `/review` | コードの準拠性確認 | 実装完了後 |
-| `/diagnose` | 根本原因分析ワークフロー | デバッグ、トラブルシューティング |
-| `/reverse-engineer` | コードからPRD/Design Docを生成 | 既存システムのドキュメント化 |
-
-フロントエンド用（`/front-design`（UI Spec + Design Doc）, `/front-build`, `/front-review`, `/front-plan`）やユーティリティコマンド（`/add-integration-tests`, `/update-doc`）も利用できます。
-
-[コマンドの詳細はこちら →](docs/guides/ja/use-cases.md)
-
 ## 🤖 Claude Code ワークフロー
 
 ```mermaid

package/README.md

@@ -19,15 +19,16 @@
 1. [Quick Start (3 Steps)](#-quick-start-3-steps)
 2. [Updating Existing Projects](#-updating-existing-projects)
 3. [Beyond Vibe Coding: Why Sub Agents?](#-beyond-vibe-coding-why-sub-agents)
-4. [Skills System](#-skills-system)
-5. [Built with This Boilerplate](#-built-with-this-boilerplate)
-6. [Documentation & Guides](#-documentation--guides)
-7. [Slash Commands](#-slash-commands)
-8. [Development Workflow](#-claude-code-workflow)
-9. [Project Structure](#-project-structure)
-10. [Package Manager Configuration](#-package-manager-configuration)
-11. [Multilingual Support](#-multilingual-support)
-12. [FAQ](#-faq)
+4. [Slash Commands](#-slash-commands)
+5. [Customizing Skills](#-customizing-skills)
+6. [Skills System](#-skills-system)
+7. [Built with This Boilerplate](#-built-with-this-boilerplate)
+8. [Documentation & Guides](#-documentation--guides)
+9. [Development Workflow](#-claude-code-workflow)
+10. [Project Structure](#-project-structure)
+11. [Package Manager Configuration](#-package-manager-configuration)
+12. [Multilingual Support](#-multilingual-support)
+13. [FAQ](#-faq)
 
 ## ⚡ Quick Start (3 Steps)
 
@@ -102,7 +103,7 @@ If your project was created before the update feature, just run `npx create-ai-p
 
 ## 🚀 Beyond Vibe Coding: Why Sub Agents?
 
-As teams move beyond vibe coding, **agentic coding** — delegating structured workflows to specialized AI agents — is becoming the professional standard. This boilerplate implements that approach with Claude Code sub-agents:
+As teams move beyond vibe coding, **agentic coding** — delegating structured workflows to specialized AI agents — is gaining traction as a practical approach. This boilerplate implements that approach with Claude Code sub-agents:
 
 **Traditional AI coding struggles with:**
 - ❌ Losing context in long sessions
@@ -124,6 +125,45 @@ This works because Claude Code's sub-agent mechanism runs each agent in its own
 
 *Sub agents working together on a TypeScript project*
 
+## 📝 Slash Commands
+
+Essential commands for Claude Code:
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/implement` | End-to-end feature development | New features |
+| `/task` | Single task with skill-based precision | Bug fixes, small changes |
+| `/design` | Create design docs only | Architecture planning |
+| `/plan` | Create work plan from design | After design approval |
+| `/build` | Execute from existing plan | Resume work |
+| `/review` | Check code compliance | Post-implementation |
+| `/diagnose` | Root cause analysis workflow | Debugging, troubleshooting |
+| `/reverse-engineer` | Generate PRD/Design Docs from code | Legacy system documentation |
+| `/create-skill` | Create a new skill through interactive dialog | Adding project-specific rules |
+| `/refine-skill` | Modify an existing skill with quality review | Improving skill accuracy |
+
+Frontend equivalents (`/front-design` for UI Spec + Design Doc, `/front-build`, `/front-review`, `/front-plan`) and utility commands (`/add-integration-tests`, `/update-doc`) are also available.
+
+[Full command reference →](docs/guides/en/use-cases.md)
+
+## 🌱 Customizing Skills
+
+This boilerplate ships with general-purpose skills that work out of the box. But skills reach their full potential when you tailor them to your project — your coding conventions, domain constraints, and team decisions.
+
+Think of the included skills as a baseline. The next step is making them yours:
+
+- **`/project-inject`** — Capture project-specific prerequisites (run once, referenced every session)
+- **`/create-skill`** — Create a new skill through interactive dialog
+- **`/refine-skill`** — Improve an existing skill with optimization review
+
+For principles and best practices on writing effective skills, see the [Skills Editing Guide](docs/guides/en/skills-editing-guide.md).
+
+### Validating Skill Effectiveness
+
+Creating a skill is one thing — knowing whether it actually improves agent behavior is another. Skills interact with each other and with project context, so the only reliable way to know is to run with and without the skill and compare results.
+
+[rashomon](https://github.com/shinpr/rashomon) is a Claude Code plugin for this. Use it when you want evidence, not intuition, that a skill change made things better.
+
 ## 🎨 Skills System
 
 This boilerplate provides the principles used in agentic implementation workflows as skills, making them available for reference in everyday tasks as needed.
@@ -171,25 +211,6 @@ Both were built using the default `/implement` workflow — no manual agent orch
 - **[Skills Editing Guide](docs/guides/en/skills-editing-guide.md)** - Add library docs, team rules, and project-specific knowledge for AI
 - **[Design Philosophy](https://dev.to/shinpr/zero-context-exhaustion-building-production-ready-ai-coding-teams-with-claude-code-sub-agents-31b)** - Why this approach works
 
-## 📝 Slash Commands
-
-Essential commands for Claude Code:
-
-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/implement` | End-to-end feature development | New features |
-| `/task` | Single task with skill-based precision | Bug fixes, small changes |
-| `/design` | Create design docs only | Architecture planning |
-| `/plan` | Create work plan from design | After design approval |
-| `/build` | Execute from existing plan | Resume work |
-| `/review` | Check code compliance | Post-implementation |
-| `/diagnose` | Root cause analysis workflow | Debugging, troubleshooting |
-| `/reverse-engineer` | Generate PRD/Design Docs from code | Legacy system documentation |
-
-Frontend equivalents (`/front-design` for UI Spec + Design Doc, `/front-build`, `/front-review`, `/front-plan`) and utility commands (`/add-integration-tests`, `/update-doc`) are also available.
-
-[Full command reference →](docs/guides/en/use-cases.md)
-
 ## 🤖 Claude Code Workflow
 
 ```mermaid
@@ -211,19 +232,22 @@ Generate PRD and Design Docs from existing code:
 ```mermaid
 graph TB
     subgraph Phase1[Phase 1: PRD Generation]
-        CMD["/reverse-engineer"] --> SD[scope-discoverer unified]
-        SD --> PRD[prd-creator]
+        SD[scope-discoverer] --> PRD[prd-creator]
         PRD --> CV1[code-verifier]
         CV1 --> DR1[document-reviewer]
+        DR1 -->|Revision needed| PRD
+        DR1 -->|Approved| NEXT1[Next unit]
     end
 
     subgraph Phase2[Phase 2: Design Doc Generation]
         TD[technical-designer] --> CV2[code-verifier]
         CV2 --> DR2[document-reviewer]
-        DR2 --> DONE[Complete]
+        DR2 -->|Revision needed| TD
+        DR2 -->|Approved| NEXT2[Next unit]
     end
 
-    DR1 --> |"All PRDs Approved (reuse scope)"| TD
+    NEXT1 -->|"All PRDs Approved (reuse scope)"| TD
+    NEXT2 --> REPORT[Final report]
 ```
 
 ### How It Works
@@ -321,7 +345,7 @@ A: Yes — create a custom skill under `.claude/skills/` with the relevant URLs.
 A: `/project-inject` (once) → `/implement` (features) → auto quality checks → commit
 
 **Q: How is this different from Copilot/Cursor?**
-A: Those help write code. This manages entire development lifecycle with specialized agents.
+A: Those tools focus on code writing assistance. This boilerplate provides a structured development lifecycle managed by specialized agents.
 
 **Q: What is agentic coding and how does this boilerplate support it?**
 A: Agentic coding delegates structured workflows to specialized AI agents instead of relying on conversational prompting. This boilerplate provides pre-configured sub-agents, CLAUDE.md rules, and quality checks so you can adopt that approach without building the scaffolding yourself.

package/docs/guides/en/skills-editing-guide.md

@@ -195,6 +195,8 @@ Standard error format: { success: false, error: string, code: number }
 Check for duplication between files and eliminate contradictions and redundancy.
 Eliminating duplication also reduces maintenance costs by preventing notation inconsistencies from update omissions.
 
+Note: there is a tradeoff between DRY and skill self-containment. If a skill requires context from another skill to be understood, the reader (both human and LLM) has to chase references. When a piece of information is central to a skill's decision-making, it may be worth repeating rather than forcing a cross-reference. Use judgment — eliminate *accidental* duplication, but don't sacrifice clarity for purity.
+
 ### 4. Appropriately Aggregate Responsibilities
 
 Consolidating related content in one skill maintains single responsibility and prevents unnecessary context mixing in tasks.
@@ -355,6 +357,14 @@ All 9 principles are practiced across these skills, serving as practical referen
 3. Add one specific example
 4. Convert negative form to positive form
 
+## Validating Skill Effectiveness
+
+The 9 principles and `/create-skill` / `/refine-skill` help you write better skills, but writing and validating are different problems. Skills interact with each other and with project context, so the only reliable way to know whether a change actually improved agent behavior is to run the task with and without the skill and compare results.
+
+[rashomon](https://github.com/shinpr/rashomon) is a Claude Code plugin for evidence-based skill validation. Its `/recipe-eval-skill` command runs your task in isolated environments and compares results to classify whether the difference is a real improvement or just variance.
+
+Use `/create-skill` and `/refine-skill` for quick iteration, and rashomon when you want proof that a skill change made things better.
+
 ## Summary
 
 Well-written skills stabilize LLM output. By following the 9 principles and continuously refining your skills, you can maximize LLM capabilities. Build the optimal skill set for your project through regular implementation review and improvement.

package/docs/guides/ja/skills-editing-guide.md

@@ -144,12 +144,12 @@ See [examples.md](examples.md) for usage patterns
 ## LLMの実行精度を最大化する9つの原則
 
 スキル作成の原則を9つ紹介します。
-スキル新規作成には`/create-skill`、既存スキルの品質レビュー付き修正には`/refine-skill`コマンドを提供しています。ただしLLMは「生成後に出力と考え方を突き合わせなければ課題に到達しづらい」傾向があるため、対話的にスキルを修正することを最終的には推奨します。
+スキル新規作成には`/create-skill`、既存スキルの品質レビュー付き修正には`/refine-skill`コマンドを提供しています。ただしLLMは「生成後に出力と考え方を突き合わせなければ課題に到達しづらい」傾向があるため、ツールで生成した後は対話的にスキルを修正することを推奨します。
 
 ### 1. 最小記述で最大精度を実現する（コンテキスト圧迫 vs 実行精度）
 
 コンテキストは貴重なリソースです。冗長な説明を避け、本質的な情報のみを記述します。
-一方で、ただ短くすればいいという訳ではなく、判断に迷わない最小限の記述でなければいけません。
+一方で、ただ短くすればいいという訳ではなく、判断に迷わない最小限の記述である必要があります。
 
 ```markdown
 ❌ 冗長な記述（24文字）
@@ -195,6 +195,8 @@ See [examples.md](examples.md) for usage patterns
 ファイル間の重複もチェックし、矛盾や冗長性を排除します。
 更新漏れによる表記揺れのリスクもあるため、重複の排除はメンテナンスコストの低下にもつながります。
 
+ただし、DRYとスキルの自己完結性にはトレードオフがあります。あるスキルの判断に必要な情報が別のスキルにしかない場合、読み手（人間もLLMも）は参照を追いかける必要が生じます。スキルの意思決定に不可欠な情報であれば、相互参照を強いるより繰り返す方が適切な場合もあります。排除すべきは*意図せず生じた*重複であり、明確さを犠牲にしてまで原則への忠実さを追求する必要はありません。
+
 ### 4. 責務を適切に集約する
 
 関連する内容は1つのスキルにまとめることで単一責務を維持でき、タスクに不要なコンテキストの混入を防げます。
@@ -355,6 +357,14 @@ LLMは冒頭の情報により注意を払います。最重要事項を先頭
 3. 具体例を1つ追加
 4. 否定形を肯定形に変換
 
+## スキルの効果検証
+
+9つの原則と`/create-skill`・`/refine-skill`はスキルの作成・改善を支援しますが、作ることと効果を確認することは別の問題です。スキルは互いに影響し合い、プロジェクトのコンテキストとも相互作用するため、変更が本当に挙動を改善したかは実際に動かして比較するしかありません。
+
+[rashomon](https://github.com/shinpr/rashomon)はエビデンスに基づくスキル検証のためのClaude Codeプラグインです。`/recipe-eval-skill`コマンドが隔離された環境でタスクを実行し、結果を比較することで、差異が実質的な改善なのか単なるバラつきなのかを分類します。
+
+`/create-skill`と`/refine-skill`は手軽な反復に、rashomonはスキル変更が本当に改善につながったか証拠が欲しいときに使い分けてください。
+
 ## まとめ
 
 効果的なスキルはLLMの生成を安定させます。9つの原則を意識し、継続的に最適化することでLLMの能力を最大限に引き出すことができます。定期的な実装結果の振り返りと改善を繰り返し、プロジェクトに最適なスキルセットを構築していきましょう。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ai-project",
-  "version": "1.20.2",
+  "version": "1.20.3",
   "packageManager": "npm@10.8.2",
   "description": "TypeScript boilerplate with skills and sub-agents for Claude Code. Prevents context exhaustion through role-based task splitting.",
   "keywords": [