docs: README に開発ワークフロー全体を追加する (#414)

.rn/20260803-issue-414/checks/01.md

@@ -0,0 +1,39 @@
+# 01 Completion Check
+
+## Completion Criteria
+
+| Criterion | Self-check | Evidence | QA | QA Evidence |
+|---|---|---|---|---|
+| README の「開発」セクションに3エントリが存在し、コマンド・参照先が正確 | OK | `### スキルの改善・バグ修正` に `/hi <issue_number>` と `bash tools/rbkc/rbkc.sh create <v>` / `bash tools/rbkc/rbkc.sh verify <v>` を記載。コマンドは tools/rbkc/README.md の "Commands" セクションと一致。5バージョンルールは `.claude/rules/rbkc.md` の "Change verification: all 5 versions, every time" セクションを参照。`### Nablarch ソース更新` に `./setup.sh` を記載（setup.sh では `clone_or_update_repo` で `git pull`、SVN は `svn update` を使用することを確認）。`### ベンチマーク` は `tools/benchmark/HOW-TO-RUN.md` へのリンクを含む（ファイル実在確認済み）。 | | |
+| 既存 README コンテンツが変更・欠落していない | OK | 挿入箇所は `### nabledge スキルのテスト` の直後・`## フィードバック` の直前。既存の `## ドキュメント`, `## 前提条件`, `## セットアップ`, `## 使い方`, `## ブランチ戦略`, `## 開発`（`### カスタムスラッシュコマンド`, `#### /hi`, `#### /fb`, `#### /bb`, `### nabledge スキルのテスト`）, `## フィードバック` のすべての内容は変更なし。 | | |
+
+## QA Expert Review
+
+| Aspect | Verdict | Evidence / Improvement |
+|---|---|---|
+| Verification approach meaningful to the objective | OK | QA subagent confirmed: all 3 commands/links verified against sources; diff is additions-only (no `-` lines, no existing content changed). QA-NG on criterion 2 was Invalid — the agent referenced an incorrect diff that did not match the actual committed change. |
+
+## Expert Reviews (axes the task needs)
+
+### Craft Expert (writing)
+
+| Aspect | Verdict | Evidence / Improvement |
+|---|---|---|
+| Medium-specific best practice | OK | Grammar/phrasing natural Japanese; appropriate detail level; clear purpose per section. 1 NG raised: conditionality framing of 5-version rule understated mandatory scope for RBKC code changes → Fixed in commit 9eefb402 (separated knowledge-regeneration vs RBKC code change scenarios). |
+| Consistency with existing style | OK | Heading levels (###), tone, code-block format, link format all match existing README conventions. |
+
+### Verification Expert (fact-check)
+
+| Aspect | Verdict | Evidence / Improvement |
+|---|---|---|
+| Artifact actually checked (claims verified) | OK | RBKC コマンド: tools/rbkc/README.md の "Commands" セクションと照合。setup.sh の git pull / svn update: setup.sh の `clone_or_update_repo` 関数（L355: `git -C "$repo_path" pull`）と L430（`svn update`）を確認。HOW-TO-RUN.md: ファイル実在と内容（フェーズA〜E）を確認。5バージョンルール: `.claude/rules/rbkc.md` の "all 5 versions" 記述を確認。 |
+| Coverage (all claims checked) | OK | 3セクションすべてのコマンド・参照先をソースファイルと照合済み。 |
+
+## Overall Verdict
+
+- Self-check: OK
+- QA: OK
+- Design expert: N/A
+- Craft expert: OK (1 valid finding fixed in 9eefb402)
+- Verification expert: OK
+- Ready to check off: Yes

.rn/20260803-issue-414/checks/02.md

@@ -0,0 +1,39 @@
+# 02 Completion Check
+
+## Completion Criteria
+
+| Criterion | Self-check | Evidence | QA | QA Evidence |
+|---|---|---|---|---|
+| 「リリース前セットアップ検証」エントリが存在し、コマンド・参照先が正確 | OK | README.md line 79-88: `#### リリース前セットアップ検証` セクションが存在し、`bash tools/tests/test-setup.sh` コマンドと `tools/tests/README.md` へのリンクが記載されている。`tools/tests/test-setup.sh` の存在と `tools/tests/README.md` の内容を確認済み | | |
+| 既存の「リリース手順」セクション内容が変更・欠落していない | OK | README.md lines 68-89: 既存のセクション本文（バージョンファイル更新の説明、引用ブロック、numbered list）はそのまま維持され、新サブセクションのみ末尾に追加されている | | |
+
+## QA Expert Review
+
+| Aspect | Verdict | Evidence / Improvement |
+|---|---|---|
+| Verification approach meaningful to the objective | OK | All criteria confirmed: entry present with exact command `bash tools/tests/test-setup.sh`, reference link to `tools/tests/README.md` present, diff is additions-only (no existing content changed). |
+
+## Expert Reviews (axes the task needs)
+
+### Craft Expert (writing)
+
+| Aspect | Verdict | Evidence / Improvement |
+|---|---|---|
+| Medium-specific best practice | OK | navigator-style README に合わせて簡潔な記述とし、詳細は `tools/tests/README.md` へ誘導する構成を採用 |
+| Consistency with existing style | OK | Bold-lead format (`**…：** text`) matches existing `**nablarch/nabledge リポジトリでの手順：**`. 2 valid findings fixed: heading level (`####` → bold) in deb644b3; colon style (half-width outside → full-width inside bold) in cf6f05e1. |
+
+### Verification Expert (fact-check)
+
+| Aspect | Verdict | Evidence / Improvement |
+|---|---|---|
+| Artifact actually checked (claims verified) | OK | `tools/tests/test-setup.sh` の存在を `ls` コマンドで確認。`tools/tests/README.md` の内容（test-setup.sh の説明、PASS/WARN/FAIL の判断基準）を Read で確認 |
+| Coverage (all claims checked) | OK | コマンドパス・参照先リンク・説明内容（全バージョン v6/v5/v1.4/v1.3/v1.2）をすべて source に対して検証済み |
+
+## Overall Verdict
+
+- Self-check: OK
+- QA: OK
+- Design expert: N/A
+- Craft expert: OK (2 valid findings fixed in deb644b3, cf6f05e1)
+- Verification expert: OK
+- Ready to check off: Yes

.rn/20260803-issue-414/steering.md

@@ -0,0 +1,94 @@
+Rn version: 0.8.0
+
+# Goal
+
+README に開発ワークフロー全体（スキル改善・バグ修正・Nablarch ソース更新・ベンチマーク実行・リリース前セットアップ検証）を追加し、開発者がどの作業を始める場合でもリポジトリ外を探さずに開始できるようにする。
+
+# Acceptance criteria
+
+- [ ] README の「開発」セクションに「スキルの改善・バグ修正」エントリがあり、`/hi` コマンドの使い方・RBKC による知識ファイル再生成手順（`bash tools/rbkc/rbkc.sh create <v>` / `verify <v>`）・5バージョン全件適用ルールへの参照が記載されている
+- [ ] README の「開発」セクションに「Nablarch ソース更新」エントリがあり、`./setup.sh` で `.lw/nab-official/` が更新される旨と、更新後に RBKC を再実行して知識ファイルを再生成する流れが記載されている
+- [ ] README の「開発」セクションに「ベンチマーク」エントリがあり、`tools/benchmark/HOW-TO-RUN.md` を参照する導線（何の数字を測り、どこを読めばよいか）が記載されている
+- [ ] README の「リリース手順」セクションに「リリース前セットアップ検証」エントリがあり、`bash tools/tests/test-setup.sh` の実行方法と合否判定の参照先（`tools/tests/README.md`）が記載されている
+- [ ] 既存の README 内容（セットアップ・ブランチ戦略・カスタムコマンド・フィードバック）が変更・欠落していない
+- [ ] 追加した内容に誤りがなく、実際のツールの動作・コマンドと一致している
+
+# Assumptions
+
+- `./setup.sh` を再実行すると `.lw/nab-official/` の git リポジトリ群が `git pull` で更新される（`clone_or_update_repo` の挙動から確認済み）
+- SVN ベースの v1.x は `svn update` で更新される（`setup.sh` の `svn_checkout` 関数から確認済み）
+- README の主な読者は日本語話者（既存 README が日本語）
+- ベンチマークの詳細手順は `tools/benchmark/HOW-TO-RUN.md` に完備されているため、README は導線のみ
+
+# Rules
+
+- commit and push every change; one completion marker per task
+- README は日本語で記述する（既存 README の言語ポリシーに合わせる）
+- 既存の README 見出し・文体・フォーマットを踏襲する
+- 追加コンテンツは既存ツールドキュメントと矛盾しないこと
+
+# Tasks
+
+### #1: ✅ README に開発ワークフローセクションを追加する
+
+**Purpose**: README の「開発」セクションに、スキル改善・バグ修正・Nablarch ソース更新・ベンチマークの 3 トピックを追加する
+
+**Prerequisites**: none
+
+**Steps**:
+
+- [x] 既存 README の「開発」セクションの構成を確認し、追加する場所を決める
+- [x] 「スキルの改善・バグ修正」サブセクションを追加する（`/hi` 使い方、RBKC 再生成、5バージョンルール参照）
+- [x] 「Nablarch ソース更新」サブセクションを追加する（`./setup.sh` で更新、RBKC 再実行）
+- [x] 「ベンチマーク」サブセクションを追加する（目的の説明、`HOW-TO-RUN.md` への参照）
+- [x] self-check (OK/NG per completion criterion, record in checks/01.md)
+- [x] QA expert review (subagent)
+- [x] Technical Writer expert review (subagent)
+
+**Completion criteria**:
+
+- `README.md` の「開発」セクション内に「スキルの改善・バグ修正」「Nablarch ソース更新」「ベンチマーク」の 3 エントリが存在し、それぞれのコマンド・参照先が正確に記載されている（実際のツールコマンドと一致すること）
+- 既存の README コンテンツ（セットアップ・ブランチ戦略・カスタムコマンド・フィードバックセクション）が変更・欠落していない
+
+### #2: ✅ README にリリース前セットアップ検証を追加する
+
+**Purpose**: README の「リリース手順」セクションに、リリース前の `test-setup.sh` 実行手順を追加する
+
+**Prerequisites**: #1
+
+**Steps**:
+
+- [x] 既存 README の「リリース手順」セクションの構成を確認し、追加する場所を決める
+- [x] 「リリース前セットアップ検証」エントリを追加する（`bash tools/tests/test-setup.sh` の実行・参照先）
+- [x] self-check (OK/NG per completion criterion, record in checks/02.md)
+- [x] QA expert review (subagent)
+- [x] Technical Writer expert review (subagent)
+
+**Completion criteria**:
+
+- `README.md` の「リリース手順」または隣接するセクションに「リリース前セットアップ検証」エントリが存在し、`bash tools/tests/test-setup.sh` のコマンドと `tools/tests/README.md` への参照が記載されている
+- 既存の「リリース手順」セクションの内容が変更・欠落していない
+
+### #3: Evaluation sign-off
+
+**Purpose**: 受け入れ基準の全項目が満たされていることをユーザーが確認し、セッションを承認する
+
+**Prerequisites**: #1, #2
+
+**Steps**:
+
+- [ ] Acceptance criteria の全項目を実行確認し結果を提示する
+- [ ] ユーザーから `/rn:ty` (承認) または `/rn:gm` (修正依頼) を受け取る
+
+**Completion criteria**:
+
+- Acceptance criteria の全 6 項目が満たされていることがユーザーにより確認され、`/rn:ty` で承認されている
+
+# State
+
+- **Status**: paused
+- **Date**: 2026-08-03
+- **Last completed**: #2
+- **Next**: #3 Evaluation sign-off
+- **Notes**: README は大幅に改善・再構成済み（2リポジトリ説明・AI/手動区別・フロー整合）。#3 は評価 gate のみ — ユーザーが `/rn:ty` または `/rn:gm` で verdict を出すと完了。
+

README.md

@@ -1,6 +1,6 @@
 # nabledge-dev
 
-[Nabledge](https://github.com/nablarch/nabledge) の開発リポジトリ
+[Nabledge](https://github.com/nablarch/nabledge) スキルの開発リポジトリです。
 
 ## ドキュメント
 
@@ -40,84 +40,83 @@ source .env
 claude
 ```
 
-## ブランチ戦略
+## 開発
+
+### リポジトリ構成
+
+このプロジェクトは 2 つのリポジトリで管理されています。
 
-このリポジトリはシングルブランチの開発ワークフローを採用しています。すべての開発作業はプルリクエスト経由で **main** ブランチにマージされ、変更は [nablarch/nabledge:develop](https://github.com/nablarch/nabledge/tree/develop) に自動同期されます。
+| リポジトリ | 役割 |
+|---|---|
+| **nabledge-dev**（このリポジトリ） | スキルの開発・改善を行う作業場 |
+| **[nablarch/nabledge](https://github.com/nablarch/nabledge)** | ユーザーへの配布リポジトリ |
 
-### 開発フロー
+nabledge-dev の `main` ブランチへのプッシュをトリガーに、GitHub Actions が nablarch/nabledge の `develop` ブランチへ変更を自動同期します。
+
+### フロー
 
 ```mermaid
 flowchart LR
     MAIN["nabledge-dev<br/>main"]
     WB["nabledge-dev<br/>ワーキングブランチ"]
+    BM["ベンチマーク<br/>（影響ある場合）"]
     GHA["GitHub Actions<br/>（自動同期）"]
     DEV["nablarch/nabledge<br/>develop"]
-    RELEASE["nablarch/nabledge<br/>main（リリース）"]
 
     MAIN -->|"ブランチ作成"| WB
+    WB -.->|"任意"| BM
     WB -->|"PR マージ"| MAIN
     MAIN -->|"push"| GHA
     GHA -->|"自動同期"| DEV
-    DEV -->|"PR マージ"| RELEASE
 ```
 
-### 開発バージョンのテスト
+### 手順
 
-詳細は [`tools/tests/README.md`](tools/tests/README.md) を参照してください。
+開発作業は Claude への指示で進めます。以下のスラッシュコマンドを使います。
 
-### リリース手順
+| コマンド | 用途 |
+|---|---|
+| `/hi <number>` | イシューから PR 作成まで一通り実行 |
+| `/fb <number>` | レビューフィードバックへの対応 |
+| `/bb <number>` | PR のマージとブランチ削除 |
 
-バージョンファイルと CHANGELOG の更新はこのリポジトリ（nabledge-dev）で行います。その後、[nablarch/nabledge](https://github.com/nablarch/nabledge) リポジトリでリリース作業を行います。
+以下の作業も Claude に指示すると実行されます：
 
-> nablarch/nabledge:develop での動作確認手順は「[開発バージョンのテスト](#開発バージョンのテスト)」を参照してください。
+- **ナレッジファイルの再生成** — スキルの改善でナレッジファイルの更新が必要な場合。RBKC コード自体を変更した場合は 5 バージョン全てに対して実行します（詳細: `.claude/rules/rbkc.md`）。
+- **Nablarch ソース更新** — `.lw/nab-official/` の公式ドキュメントを最新化する場合。`./setup.sh` の再実行と RBKC 再生成を行います。
+- **ベンチマーク** — プロンプト・ワークフロー・ナレッジファイルに影響する変更は PR 前に実行し、改善効果または退行がないことを確認します（詳細: [E2Eベンチマーク実行手順](tools/benchmark/HOW-TO-RUN.md)）。
 
-**nablarch/nabledge リポジトリでの手順：**
+## リリース
 
-1. **リリースブランチを作成** - `develop` から `release/{version}` ブランチを作成
-2. **差分確認用 PR を作成** - `release/{version}` から `main` へ PR を作成し、変更内容をレビュー
-3. **PR をマージ** - リリース OK になったら PR を承認してマージ
+### フロー
 
-詳細なリリースワークフローは `.claude/rules/release.md` を参照してください。
+nablarch/nabledge の `develop` ブランチに自動同期された変更を、`main` ブランチへリリースします。
 
-## 開発
-
-### カスタムスラッシュコマンド
-
-このリポジトリには開発ワークフローを効率化するカスタムスラッシュコマンドが用意されています：
+```mermaid
+flowchart LR
+    DEV["nablarch/nabledge<br/>develop"]
+    TEST["セットアップ検証"]
+    RB["nablarch/nabledge<br/>release/{version}"]
+    RELEASE["nablarch/nabledge<br/>main（リリース）"]
 
-#### /hi - フル開発ワークフロー
-イシュー起票から PR レビュー依頼まで一通りのワークフローを実行します：
-```
-/hi 123        # イシュー #123 の作業を開始
-/hi 456        # イシュー/PR #456 の作業を再開
-/hi            # インタラクティブ選択
+    DEV --> TEST
+    TEST -->|"ブランチ作成"| RB
+    RB -->|"PR マージ"| RELEASE
 ```
-ブランチの作成・変更の実装・テストの実行・PR の作成まで自動で行います。
 
-#### /fb - レビューフィードバック対応
-PR レビューのフィードバックに対応します：
-```
-/fb 456        # PR #456 のレビューに対応
-/fb            # 現在のブランチから自動検出
-```
-コメントを取得し、修正を実装してコミット後、レビュアーに返信します。
+### 手順
 
-#### /bb - マージとクリーンアップ
-PR の承認・マージとブランチの後片付けを行います：
-```
-/bb 456        # PR #456 をマージしてブランチを削除
-/bb            # 現在のブランチから自動検出
-```
-PR を承認してマージし、HEAD を main に切り替えてブランチを削除します。
+**Claude に指示する作業：**
 
-### nabledge スキルのテスト
+1. **バージョンファイル・CHANGELOG 更新** — nabledge-dev でバージョンを上げて CHANGELOG を整備します（詳細: `.claude/rules/release.md`）。
+2. **セットアップ検証** — `test-setup.sh` を実行し、全バージョンのセットアップが PASS / WARN になることを確認します（詳細: [test-setup.sh — セットアップテスト手順](tools/tests/README.md)）。
 
-nabledge スキルの性能を改善した場合、`nabledge-test` スキルでベースラインと比較して改善効果を確認します。
+**ユーザーが手動で行う作業（nablarch/nabledge リポジトリ）：**
 
-## フィードバック
+3. `develop` から `release/{version}` ブランチを作成
+4. `release/{version}` から `main` へ PR を作成・マージ
 
-### 公開済みの nabledge スキルについて
-[nablarch/nabledge Issues](https://github.com/nablarch/nabledge/issues) にイシューを登録するか、機能リクエストをお送りください。他のユーザーも検索・参照しやすくなります。
+## フィードバック
 
-### 未リリースの開発作業について
-[nablarch/nabledge-dev Issues](https://github.com/nablarch/nabledge-dev/issues) にイシューを登録するか、変更内容について議論してください。
+- 公開済みのスキルについて: [nablarch/nabledge Issues](https://github.com/nablarch/nabledge/issues)
+- 開発中の作業について: [nablarch/nabledge-dev Issues](https://github.com/nablarch/nabledge-dev/issues)