From 521ac200dc416c104007c7c8aef6fd0dc9bf5fae Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 29 May 2026 15:20:13 +0900 Subject: [PATCH 1/5] docs: add tasks.md and notes.md for issue #363 Co-Authored-By: Claude Sonnet 4.6 --- .work/00363/notes.md | 33 +++++++++++++ .work/00363/tasks.md | 115 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 148 insertions(+) create mode 100644 .work/00363/notes.md create mode 100644 .work/00363/tasks.md diff --git a/.work/00363/notes.md b/.work/00363/notes.md new file mode 100644 index 000000000..06b743a28 --- /dev/null +++ b/.work/00363/notes.md @@ -0,0 +1,33 @@ +# Notes + +## 2026-05-29 + +### Issue #363 概要 + +Nablarch公式ドキュメントは詳細APIをJavadocに委ねているが、nabledge知識ファイルにJavadocが含まれていない。 +jarツールを使ってNablarchソースからMarkdownを生成し、RBKCパイプラインに追加する。 + +### 調査結果: RBKCパイプライン構造 + +- `rbkc.sh` → `scripts/run.py` の薄いシム。`create|update|delete|verify ` をサポート +- ソース: `.lw/nab-official/v{N}/` 配下の RST/MD/xlsx を `scan_sources()` でスキャン +- コンバータ: `converters/rst.py`, `converters/md.py`, `converters/xlsx_*.py`（フォーマット別） +- 出力: `.claude/skills/nabledge-{N}/knowledge/{type}/{category}/{file_id}.json` +- 現在、`:javadoc_url:` ロールはURLを捨てて表示テキストのみ残す（`rst_ast_visitor.py` L781-786） + +### 設計方針（暫定） + +**絶対制約: 既存の RST/MD/xlsx パイプラインに一切触れない** + +新フォーマット `javadoc` として追加のみ。変更対象は以下の追加のみ: +- `converters/javadoc.py` — 新規作成 +- `mappings/v*.json` — 新エントリ追加のみ +- `scan_sources()` — 新分岐追加（既存分岐に触れない） +- `_converter_for()` — 新分岐追加（既存分岐に触れない） + +→ jar の出力形式確認後（Task 0）に詳細設計を行う + +### 未解決事項 + +- jar ファイルの入手方法（issue に「実装時に提供」と記載） +- 各バージョンで対象クラスの範囲（全 public クラス vs. `:javadoc_url:` 参照のみ） diff --git a/.work/00363/tasks.md b/.work/00363/tasks.md new file mode 100644 index 000000000..35de4e4dd --- /dev/null +++ b/.work/00363/tasks.md @@ -0,0 +1,115 @@ +# Tasks: Add Javadoc knowledge to nabledge skills + +**PR**: (TBD) +**Issue**: #363 +**Updated**: 2026-05-29 + +## Rules (applied to every task) + +- 1コミット = 1タスク（粒度を守る） +- SCを満たすようタスクを分割し、このファイルで管理する +- 推測せず事実ベースで調査・作業・判断する（実物・全件を確認し、確認範囲を明示する） +- 既存の RST/MD/xlsx パイプラインには一切触れない（追加のみ） +- RBKCのcreate/verifyを変更する場合は実装前に設計書を更新してユーザーに確認する +- PRレビュー依頼前に、変更差分が想定どおりの変更のみかをチェックし、結果を作業記録に出力してユーザーに確認する +- 全タスク共通: 変更差分チェック → ユーザー確認 → PRレビュー依頼の順を守る + +--- + +## Not Started + +### Task 0: Investigate jar tool input/output format +**Goal**: SC「Investigate: Identify the input/output format of the provided jar tool (source file → Markdown)」を満たす。 +**Steps:** +- [ ] ユーザーに jar ファイルの入手方法・場所を確認する（jarはissue説明によると「実装時に提供」とある） +- [ ] jar を実際に動かしてサンプル出力（Markdown）を取得する +- [ ] 出力 Markdown の構造を全件確認する（クラス1つ分・パッケージ複数分） +- [ ] 入力形式（ソースファイルのパス指定方法・オプション）を確認する +- [ ] 調査結果を `.work/00363/notes.md` に記録する + +### Task 1: Investigate RBKC integration point (all 5 versions) +**Goal**: SC「Investigate: Determine appropriate integration point in the RBKC pipeline across all 5 versions」を満たす。 +**Steps:** +- [ ] 各バージョン（v6/v5/v1.4/v1.3/v1.2）のNablarchソースJarの取得方法を調査する（Mavenリポジトリ等） +- [ ] `.lw/nab-official/` 配下の各バージョンのディレクトリ構成を全件確認する +- [ ] 各バージョンで「どのNablarchクラスのJavadocが必要か」を調査する（RST中の `:javadoc_url:` 参照38箇所を全件確認） +- [ ] 新フォーマット（`javadoc`）を既存パイプラインに追加する場合の影響範囲を調査する + - `scan_sources()` への追加箇所 + - `_converter_for()` への追加箇所 + - `mappings/v*.json` への追加箇所 + - `verify.py` への影響（既存チェックの非適用対象にするか否か） +- [ ] 既存テスト（e2e/ut）への影響を全件確認する +- [ ] 調査結果を `.work/00363/notes.md` に記録する + +### Task 2: Design — Javadoc converter and pipeline integration +**Goal**: 実装前設計書の作成とユーザー承認。 +**前提**: Task 0, Task 1 完了後 +**Steps:** +- [ ] jar 出力 Markdown → knowledge JSON への変換仕様を設計する +- [ ] verify が Javadoc 知識ファイルをどう扱うか設計する（既存チェック全適用 / 一部除外 / 専用チェック追加） +- [ ] 全5バージョンへの適用方針を設計する（バージョン固有の差異があれば記録） +- [ ] 設計書を `tools/rbkc/docs/` に追加する +- [ ] 設計書をコミットし、PRコメントでユーザーに確認を依頼する +- [ ] ユーザー承認後に実装フェーズへ進む + +### Task 3: Implement — jar runner script (Javadoc Markdown generation) +**Goal**: 全5バージョンの全 public Nablarchクラスの Javadoc Markdown を生成する。 +**前提**: Task 2 完了後 +**Steps:** +- [ ] jar を実行して Javadoc Markdown を生成するスクリプトを作成する（`tools/rbkc/scripts/` 配下） +- [ ] 全5バージョンで動作確認する +- [ ] 生成ファイル数・内容を全件確認し、結果を作業記録に記録する + +### Task 4: Implement — Javadoc converter (`converters/javadoc.py`) +**Goal**: jar 出力 Markdown → knowledge JSON への変換器を実装する。 +**前提**: Task 2, Task 3 完了後 +**Steps:** +- [ ] `tools/rbkc/scripts/create/converters/javadoc.py` を新規作成する（既存ファイルに一切触れない） +- [ ] TDD: テストを先に書く（RED） +- [ ] 実装（GREEN） +- [ ] 全既存テストが通ることを確認する: `pytest tools/rbkc/tests/ -x` + +### Task 5: Implement — Pipeline integration (scan/classify/run) +**Goal**: 新フォーマット `javadoc` を RBKC パイプラインに追加する。 +**前提**: Task 4 完了後 +**Steps:** +- [ ] `mappings/v*.json` に Javadoc エントリを追加する（全5バージョン） +- [ ] `scan_sources()` に `.md`（Javadoc生成済みMD）のスキャン対応を追加する（既存MDスキャンと衝突しない形で） +- [ ] `_converter_for()` に `javadoc` フォーマットの dispatch を追加する +- [ ] `rbkc.sh create ` を全5バージョンで実行し、Javadoc 知識ファイルが生成されることを確認する +- [ ] 全既存テストが通ることを確認する: `pytest tools/rbkc/tests/ -x` + +### Task 6: Implement — verify compatibility (all 5 versions) +**Goal**: `rbkc.sh verify ` が全5バージョンで FAIL 増加なしで通ること。 +**前提**: Task 5 完了後 +**Steps:** +- [ ] 各バージョンの create 前後の FAIL 数をベースラインとして記録する +- [ ] `rbkc.sh create && rbkc.sh verify ` を全5バージョンで実行する +- [ ] FAIL 差分を分析する（想定外の増加があれば RBKC 側を修正する） +- [ ] verify に Javadoc 専用チェックが必要な場合は設計書を更新してユーザー確認を得る +- [ ] 全バージョンで FAIL 増加なしを確認する + +### Task 7: Benchmark — verify scores do not decrease (all 5 versions) +**Goal**: SC「Benchmark scores for all 5 versions do not decrease vs. baseline after adding Javadoc knowledge」を満たす。 +**前提**: Task 6 完了後 +**Steps:** +- [ ] nabledge-test ベースラインスコアを確認する（MEMORY.md 記載の最新ベースライン） +- [ ] 各バージョンでベンチマークを実行する（逐次実行 — 並列不可、tools/benchmark/run.py を使用） +- [ ] スコア比較結果を `.work/00363/notes.md` に記録する +- [ ] スコア低下があれば原因を特定して修正する + +### Task 8: Diff check and PR review request +**Goal**: 全タスク完了後、変更差分が想定どおりかをチェックしてPRを作成する。 +**前提**: Task 7 完了後 +**Steps:** +- [ ] `git diff main...HEAD --stat` で変更ファイル一覧を確認する +- [ ] 想定外の変更がないかを全件チェックし、`.work/00363/diff-check.md` に記録する +- [ ] ユーザーに確認を依頼する +- [ ] Expert review を実行する（Software Engineer + QA Engineer） +- [ ] `/pr create` でPRを作成する + +--- + +## Done + +（なし） From 1da0926b74af5e96c6e3c8c8bfbeec31ebcc1923 Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 29 May 2026 16:01:52 +0900 Subject: [PATCH 2/5] =?UTF-8?q?docs:=20update=20tasks.md=20=E2=80=94=20res?= =?UTF-8?q?tructure=20around=20design-first=20approach=20(#363)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .work/00363/tasks.md | 168 +++++++++++++++++++++++-------------------- 1 file changed, 91 insertions(+), 77 deletions(-) diff --git a/.work/00363/tasks.md b/.work/00363/tasks.md index 35de4e4dd..de504369e 100644 --- a/.work/00363/tasks.md +++ b/.work/00363/tasks.md @@ -1,6 +1,6 @@ # Tasks: Add Javadoc knowledge to nabledge skills -**PR**: (TBD) +**PR**: #365 **Issue**: #363 **Updated**: 2026-05-29 @@ -9,107 +9,121 @@ - 1コミット = 1タスク（粒度を守る） - SCを満たすようタスクを分割し、このファイルで管理する - 推測せず事実ベースで調査・作業・判断する（実物・全件を確認し、確認範囲を明示する） -- 既存の RST/MD/xlsx パイプラインには一切触れない（追加のみ） +- 既存の RST/MD/xlsx パイプラインには一切触れない（追加・変更は最小限） - RBKCのcreate/verifyを変更する場合は実装前に設計書を更新してユーザーに確認する - PRレビュー依頼前に、変更差分が想定どおりの変更のみかをチェックし、結果を作業記録に出力してユーザーに確認する - 全タスク共通: 変更差分チェック → ユーザー確認 → PRレビュー依頼の順を守る --- +## 背景・設計理解 + +### 問題の本質 + +RST内の `:java:extdoc:` (1,971件、nablarch.* 751件) が現在は表示テキストのみに変換されリンクが消える。 +その結果、知識ファイルには「クラス名のテキスト」しかなく、Javadocの詳細（メソッド・引数・戻り値・挙動）が得られない。 + +### あるべき姿 + +``` +jarツール → Javadoc MD → RBKC → api/ カテゴリの知識JSON + 閲覧用MD + ↑ +RST :java:extdoc: → 内部クロスドキュメントリンク（外部URL依存なし） +``` + +- Javadoc知識ファイルが内部に存在することで、キーワード検索・意味検索の両方から参照可能になる +- 閲覧用MDもクリッカブルなリンクになる +- 外部 `nablarch.github.io` JavadocへのURL依存が消える + +### 実装順序の理由 + +検索をどう変えるか（意味検索のindex.md構成、QAワークフローの変更点）を先に設計しないと、 +検索修正タスクの粒度・内容が決まらない。設計 → 実装 → 検索修正 → 検証 → 全バージョン展開の順。 + +--- + ## Not Started -### Task 0: Investigate jar tool input/output format -**Goal**: SC「Investigate: Identify the input/output format of the provided jar tool (source file → Markdown)」を満たす。 +### Task 0: 設計（コンバータ設計 + 検索設計） +**Goal**: 実装前に全体設計を確定し、ユーザーに承認を得る。 **Steps:** -- [ ] ユーザーに jar ファイルの入手方法・場所を確認する（jarはissue説明によると「実装時に提供」とある） -- [ ] jar を実際に動かしてサンプル出力（Markdown）を取得する -- [ ] 出力 Markdown の構造を全件確認する（クラス1つ分・パッケージ複数分） -- [ ] 入力形式（ソースファイルのパス指定方法・オプション）を確認する -- [ ] 調査結果を `.work/00363/notes.md` に記録する - -### Task 1: Investigate RBKC integration point (all 5 versions) -**Goal**: SC「Investigate: Determine appropriate integration point in the RBKC pipeline across all 5 versions」を満たす。 +- [ ] jarツールの入出力形式を確認する（ユーザーからjar入手後） +- [ ] コンバータ設計: + - [ ] Javadoc MD → 知識JSON のスキーマ設計（`api/` カテゴリ） + - [ ] `:java:extdoc:` の内部リンク解決方式（FQCNからfile_idを引く方法） + - [ ] verify への影響設計（既存チェックの適用範囲） +- [ ] 検索設計: + - [ ] 意味検索: `index.md` の構成変更（`api/` セクション追加 or 分離） + - [ ] 意味検索: `semantic-search.md` の変更点（api/ セクションの扱い） + - [ ] QAワークフロー: `qa.md` の変更点（Javadoc質問への対応） + - [ ] キーワード検索: 変更不要か確認（スキャン対象に自動追加される） +- [ ] 設計書を `tools/rbkc/docs/` または `.work/00363/` に作成する +- [ ] コミット・プッシュしてユーザーに確認を依頼する +- [ ] ユーザー承認後に Task 1 へ進む + +### Task 1: jarツール実行 + Javadoc MD 生成確認 +**Goal**: SC「Identify the input/output format of the provided jar tool」を満たす。 +**前提**: Task 0 完了後 **Steps:** -- [ ] 各バージョン（v6/v5/v1.4/v1.3/v1.2）のNablarchソースJarの取得方法を調査する（Mavenリポジトリ等） -- [ ] `.lw/nab-official/` 配下の各バージョンのディレクトリ構成を全件確認する -- [ ] 各バージョンで「どのNablarchクラスのJavadocが必要か」を調査する（RST中の `:javadoc_url:` 参照38箇所を全件確認） -- [ ] 新フォーマット（`javadoc`）を既存パイプラインに追加する場合の影響範囲を調査する - - `scan_sources()` への追加箇所 - - `_converter_for()` への追加箇所 - - `mappings/v*.json` への追加箇所 - - `verify.py` への影響（既存チェックの非適用対象にするか否か） -- [ ] 既存テスト（e2e/ut）への影響を全件確認する +- [ ] jarツールを実際に実行してサンプル出力（MD）を取得する +- [ ] 出力MDの構造を全件確認する（クラス1つ分・複数クラス） +- [ ] 設計（Task 0）との差異があれば設計を修正する - [ ] 調査結果を `.work/00363/notes.md` に記録する -### Task 2: Design — Javadoc converter and pipeline integration -**Goal**: 実装前設計書の作成とユーザー承認。 +### Task 2: コンバータ実装（`converters/javadoc.py` + `:java:extdoc:` 内部リンク） +**Goal**: Javadoc MDを知識JSON/閲覧用MDに変換し、`:java:extdoc:` が内部リンクになること。 **前提**: Task 0, Task 1 完了後 **Steps:** -- [ ] jar 出力 Markdown → knowledge JSON への変換仕様を設計する -- [ ] verify が Javadoc 知識ファイルをどう扱うか設計する（既存チェック全適用 / 一部除外 / 専用チェック追加） -- [ ] 全5バージョンへの適用方針を設計する（バージョン固有の差異があれば記録） -- [ ] 設計書を `tools/rbkc/docs/` に追加する -- [ ] 設計書をコミットし、PRコメントでユーザーに確認を依頼する -- [ ] ユーザー承認後に実装フェーズへ進む - -### Task 3: Implement — jar runner script (Javadoc Markdown generation) -**Goal**: 全5バージョンの全 public Nablarchクラスの Javadoc Markdown を生成する。 -**前提**: Task 2 完了後 +- [ ] `tools/rbkc/scripts/create/converters/javadoc.py` を新規作成（TDD: テスト先行） +- [ ] `rst_ast_visitor.py` の `:java:extdoc:` 処理を内部リンク出力に変更 + - 変更前: 表示テキストのみ返す + - 変更後: 対応するJavadoc知識JSONが存在すれば内部クロスドキュメントリンク、なければ表示テキスト（後退しない） +- [ ] mappings/v6.json に `api/` カテゴリエントリを追加 +- [ ] `scan_sources()` / `_converter_for()` に javadoc フォーマットの追加分岐 +- [ ] `rbkc.sh create 6 && rbkc.sh verify 6` を実行し FAIL 増加なしを確認 +- [ ] 全既存テストが通ることを確認: `pytest tools/rbkc/tests/ -x` + +### Task 3: 検索修正（semantic-search + qa ワークフロー） +**Goal**: 意味検索・QAワークフローから Javadoc 知識ファイルが参照されること。 +**前提**: Task 2 完了後（index.mdにapi/エントリが生成されていること） **Steps:** -- [ ] jar を実行して Javadoc Markdown を生成するスクリプトを作成する（`tools/rbkc/scripts/` 配下） -- [ ] 全5バージョンで動作確認する -- [ ] 生成ファイル数・内容を全件確認し、結果を作業記録に記録する - -### Task 4: Implement — Javadoc converter (`converters/javadoc.py`) -**Goal**: jar 出力 Markdown → knowledge JSON への変換器を実装する。 -**前提**: Task 2, Task 3 完了後 +- [ ] `workflows/semantic-search.md` を設計通りに更新（api/ セクションの扱い） +- [ ] `workflows/qa.md` を設計通りに更新（Javadoc質問への対応） +- [ ] キーワード検索: スキャン対象に自動追加されていることを確認（変更不要なら記録） +- [ ] 手動動作確認: 「`UniversalDao#exist` の戻り値は？」「DAOで存在チェックするには？」の両方で Javadoc 知識ファイルが参照されることを確認 + +### Task 4: ベンチマークシナリオ追加 + v6 検証 +**Goal**: SC「nabledge can correctly answer questions about Javadoc-deferred API details」「Benchmark scores do not decrease」を満たす。 +**前提**: Task 3 完了後 **Steps:** -- [ ] `tools/rbkc/scripts/create/converters/javadoc.py` を新規作成する（既存ファイルに一切触れない） -- [ ] TDD: テストを先に書く（RED） -- [ ] 実装（GREEN） -- [ ] 全既存テストが通ることを確認する: `pytest tools/rbkc/tests/ -x` - -### Task 5: Implement — Pipeline integration (scan/classify/run) -**Goal**: 新フォーマット `javadoc` を RBKC パイプラインに追加する。 -**前提**: Task 4 完了後 +- [ ] nabledge-test に Javadoc 参照質問のシナリオを追加する（例: `UniversalDao#exist` の挙動） +- [ ] v6 ベンチマークを実行する（逐次実行 — 並列不可） +- [ ] 既存シナリオのスコアがベースライン（95.9%）から低下していないことを確認 +- [ ] 新シナリオが正答することを確認 +- [ ] 結果を `.work/00363/notes.md` に記録する + +### Task 5: 全バージョン適用（v5 / v1.4 / v1.3 / v1.2） +**Goal**: SC「all 5 versions」を満たす。 +**前提**: Task 4（v6 検証 OK）後 **Steps:** -- [ ] `mappings/v*.json` に Javadoc エントリを追加する（全5バージョン） -- [ ] `scan_sources()` に `.md`（Javadoc生成済みMD）のスキャン対応を追加する（既存MDスキャンと衝突しない形で） -- [ ] `_converter_for()` に `javadoc` フォーマットの dispatch を追加する -- [ ] `rbkc.sh create ` を全5バージョンで実行し、Javadoc 知識ファイルが生成されることを確認する -- [ ] 全既存テストが通ることを確認する: `pytest tools/rbkc/tests/ -x` - -### Task 6: Implement — verify compatibility (all 5 versions) -**Goal**: `rbkc.sh verify ` が全5バージョンで FAIL 増加なしで通ること。 +- [ ] mappings/v5.json, v1.4.json, v1.3.json, v1.2.json に `api/` カテゴリエントリを追加 +- [ ] 各バージョンで jarツールを実行して Javadoc MD を生成する +- [ ] `rbkc.sh create && rbkc.sh verify ` を全4バージョンで実行し FAIL 増加なしを確認 +- [ ] 全バージョンのベンチマークを実行し、スコア低下なしを確認（逐次実行） + +### Task 6: 差分チェック + PR レビュー依頼 +**Goal**: 全タスク完了後、変更差分が想定どおりかをチェックしてレビュー依頼。 **前提**: Task 5 完了後 **Steps:** -- [ ] 各バージョンの create 前後の FAIL 数をベースラインとして記録する -- [ ] `rbkc.sh create && rbkc.sh verify ` を全5バージョンで実行する -- [ ] FAIL 差分を分析する（想定外の増加があれば RBKC 側を修正する） -- [ ] verify に Javadoc 専用チェックが必要な場合は設計書を更新してユーザー確認を得る -- [ ] 全バージョンで FAIL 増加なしを確認する - -### Task 7: Benchmark — verify scores do not decrease (all 5 versions) -**Goal**: SC「Benchmark scores for all 5 versions do not decrease vs. baseline after adding Javadoc knowledge」を満たす。 -**前提**: Task 6 完了後 -**Steps:** -- [ ] nabledge-test ベースラインスコアを確認する（MEMORY.md 記載の最新ベースライン） -- [ ] 各バージョンでベンチマークを実行する（逐次実行 — 並列不可、tools/benchmark/run.py を使用） -- [ ] スコア比較結果を `.work/00363/notes.md` に記録する -- [ ] スコア低下があれば原因を特定して修正する - -### Task 8: Diff check and PR review request -**Goal**: 全タスク完了後、変更差分が想定どおりかをチェックしてPRを作成する。 -**前提**: Task 7 完了後 -**Steps:** - [ ] `git diff main...HEAD --stat` で変更ファイル一覧を確認する - [ ] 想定外の変更がないかを全件チェックし、`.work/00363/diff-check.md` に記録する - [ ] ユーザーに確認を依頼する - [ ] Expert review を実行する（Software Engineer + QA Engineer） -- [ ] `/pr create` でPRを作成する +- [ ] `/pr create` でPRを更新する --- ## Done -（なし） +- [x] `.work/00363/tasks.md` と `notes.md` 作成 — committed `521ac200d` +- [x] PR #365 作成 From f6fde7a770e13078daf06925aa735bfdab1b301b Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 29 May 2026 16:06:08 +0900 Subject: [PATCH 3/5] =?UTF-8?q?docs:=20update=20tasks.md=20=E2=80=94=20add?= =?UTF-8?q?=20scenario/benchmark=20steps,=20fix=20task=20order=20(#363)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .work/00363/tasks.md | 109 ++++++++++++++++++++----------------------- 1 file changed, 51 insertions(+), 58 deletions(-) diff --git a/.work/00363/tasks.md b/.work/00363/tasks.md index de504369e..5392480e5 100644 --- a/.work/00363/tasks.md +++ b/.work/00363/tasks.md @@ -9,7 +9,7 @@ - 1コミット = 1タスク（粒度を守る） - SCを満たすようタスクを分割し、このファイルで管理する - 推測せず事実ベースで調査・作業・判断する（実物・全件を確認し、確認範囲を明示する） -- 既存の RST/MD/xlsx パイプラインには一切触れない（追加・変更は最小限） +- 既存の RST/MD/xlsx パイプラインへの変更は最小限 - RBKCのcreate/verifyを変更する場合は実装前に設計書を更新してユーザーに確認する - PRレビュー依頼前に、変更差分が想定どおりの変更のみかをチェックし、結果を作業記録に出力してユーザーに確認する - 全タスク共通: 変更差分チェック → ユーザー確認 → PRレビュー依頼の順を守る @@ -20,8 +20,8 @@ ### 問題の本質 -RST内の `:java:extdoc:` (1,971件、nablarch.* 751件) が現在は表示テキストのみに変換されリンクが消える。 -その結果、知識ファイルには「クラス名のテキスト」しかなく、Javadocの詳細（メソッド・引数・戻り値・挙動）が得られない。 +RST内の `:java:extdoc:` (nablarch.* 751件) が現在は表示テキストのみに変換されリンクが消える。 +Javadocの詳細（メソッド・引数・戻り値・挙動）が知識ファイルに存在しない。 ### あるべき姿 @@ -31,95 +31,88 @@ jarツール → Javadoc MD → RBKC → api/ カテゴリの知識JSON + 閲覧 RST :java:extdoc: → 内部クロスドキュメントリンク（外部URL依存なし） ``` -- Javadoc知識ファイルが内部に存在することで、キーワード検索・意味検索の両方から参照可能になる +- キーワード検索・意味検索の両方から Javadoc 知識ファイルが参照される - 閲覧用MDもクリッカブルなリンクになる -- 外部 `nablarch.github.io` JavadocへのURL依存が消える - -### 実装順序の理由 - -検索をどう変えるか（意味検索のindex.md構成、QAワークフローの変更点）を先に設計しないと、 -検索修正タスクの粒度・内容が決まらない。設計 → 実装 → 検索修正 → 検証 → 全バージョン展開の順。 +- 外部 `nablarch.github.io` Javadoc URL依存が消える --- ## Not Started -### Task 0: 設計（コンバータ設計 + 検索設計） -**Goal**: 実装前に全体設計を確定し、ユーザーに承認を得る。 -**Steps:** -- [ ] jarツールの入出力形式を確認する（ユーザーからjar入手後） -- [ ] コンバータ設計: - - [ ] Javadoc MD → 知識JSON のスキーマ設計（`api/` カテゴリ） - - [ ] `:java:extdoc:` の内部リンク解決方式（FQCNからfile_idを引く方法） - - [ ] verify への影響設計（既存チェックの適用範囲） -- [ ] 検索設計: - - [ ] 意味検索: `index.md` の構成変更（`api/` セクション追加 or 分離） - - [ ] 意味検索: `semantic-search.md` の変更点（api/ セクションの扱い） - - [ ] QAワークフロー: `qa.md` の変更点（Javadoc質問への対応） - - [ ] キーワード検索: 変更不要か確認（スキャン対象に自動追加される） -- [ ] 設計書を `tools/rbkc/docs/` または `.work/00363/` に作成する -- [ ] コミット・プッシュしてユーザーに確認を依頼する -- [ ] ユーザー承認後に Task 1 へ進む - -### Task 1: jarツール実行 + Javadoc MD 生成確認 +### Task 1: jarツール確認（入出力形式） **Goal**: SC「Identify the input/output format of the provided jar tool」を満たす。 -**前提**: Task 0 完了後 +**前提**: ユーザーからjarファイル入手後 **Steps:** - [ ] jarツールを実際に実行してサンプル出力（MD）を取得する - [ ] 出力MDの構造を全件確認する（クラス1つ分・複数クラス） -- [ ] 設計（Task 0）との差異があれば設計を修正する +- [ ] 入力形式（ソースファイルのパス指定・オプション）を確認する - [ ] 調査結果を `.work/00363/notes.md` に記録する -### Task 2: コンバータ実装（`converters/javadoc.py` + `:java:extdoc:` 内部リンク） +### Task 2: 設計書更新 → ユーザー承認 +**Goal**: 実装前に設計を確定する。jarツール出力形式を踏まえて以下を更新。 +**前提**: Task 1 完了後 +**更新対象設計書:** +- [ ] `tools/rbkc/docs/rbkc-converter-design.md` — Javadoc MD → 知識JSONの変換ルール、`:java:extdoc:` 内部リンク出力ルール +- [ ] `tools/rbkc/docs/rbkc-json-schema-design.md` — `api/` カテゴリのJSONスキーマ +- [ ] `.claude/skills/nabledge-6/workflows/semantic-search.md` — `api/` カテゴリの扱い（分離 or 混在） +- [ ] `.claude/skills/nabledge-6/workflows/qa.md` — Javadoc質問への対応 +- [ ] コミット・プッシュしてユーザーに確認を依頼する +- [ ] ユーザー承認後に Task 3 へ進む + +### Task 3: コンバータ実装 **Goal**: Javadoc MDを知識JSON/閲覧用MDに変換し、`:java:extdoc:` が内部リンクになること。 -**前提**: Task 0, Task 1 完了後 +**前提**: Task 2 完了後 **Steps:** - [ ] `tools/rbkc/scripts/create/converters/javadoc.py` を新規作成（TDD: テスト先行） -- [ ] `rst_ast_visitor.py` の `:java:extdoc:` 処理を内部リンク出力に変更 - - 変更前: 表示テキストのみ返す - - 変更後: 対応するJavadoc知識JSONが存在すれば内部クロスドキュメントリンク、なければ表示テキスト（後退しない） -- [ ] mappings/v6.json に `api/` カテゴリエントリを追加 -- [ ] `scan_sources()` / `_converter_for()` に javadoc フォーマットの追加分岐 +- [ ] `rst_ast_visitor.py` の `:java:extdoc:` 処理を内部リンク出力に変更（対応JSONが存在すれば内部リンク、なければ表示テキスト） +- [ ] `mappings/v6.json` に `api/` カテゴリエントリを追加 +- [ ] `scan_sources()` / `_converter_for()` に javadoc フォーマットの分岐を追加 - [ ] `rbkc.sh create 6 && rbkc.sh verify 6` を実行し FAIL 増加なしを確認 - [ ] 全既存テストが通ることを確認: `pytest tools/rbkc/tests/ -x` -### Task 3: 検索修正（semantic-search + qa ワークフロー） +### Task 4: 検索修正 **Goal**: 意味検索・QAワークフローから Javadoc 知識ファイルが参照されること。 -**前提**: Task 2 完了後（index.mdにapi/エントリが生成されていること） +**前提**: Task 3 完了後（index.mdにapi/エントリが生成されていること） **Steps:** -- [ ] `workflows/semantic-search.md` を設計通りに更新（api/ セクションの扱い） -- [ ] `workflows/qa.md` を設計通りに更新（Javadoc質問への対応） +- [ ] `workflows/semantic-search.md` を設計通りに更新 +- [ ] `workflows/qa.md` を設計通りに更新 - [ ] キーワード検索: スキャン対象に自動追加されていることを確認（変更不要なら記録） -- [ ] 手動動作確認: 「`UniversalDao#exist` の戻り値は？」「DAOで存在チェックするには？」の両方で Javadoc 知識ファイルが参照されることを確認 -### Task 4: ベンチマークシナリオ追加 + v6 検証 -**Goal**: SC「nabledge can correctly answer questions about Javadoc-deferred API details」「Benchmark scores do not decrease」を満たす。 -**前提**: Task 3 完了後 +### Task 5: ベンチマークシナリオ追加 +**Goal**: Javadoc参照質問に答えられることを検証するシナリオを用意する。 +**前提**: Task 4 完了後 **Steps:** -- [ ] nabledge-test に Javadoc 参照質問のシナリオを追加する（例: `UniversalDao#exist` の挙動） -- [ ] v6 ベンチマークを実行する（逐次実行 — 並列不可） -- [ ] 既存シナリオのスコアがベースライン（95.9%）から低下していないことを確認 -- [ ] 新シナリオが正答することを確認 +- [ ] 既存シナリオでは Javadoc 知識ファイルが参照されないことを確認する +- [ ] Javadoc参照質問のシナリオを新規追加する（例: 「`UniversalDao#exist` の戻り値・挙動は？」） +- [ ] 期待値（expectations）を設定する + +### Task 6: v6 検証（新シナリオ1件 → 既存スコア確認） +**Goal**: SC「nabledge can correctly answer questions about Javadoc-deferred API details」「Benchmark scores do not decrease」をv6で確認する。 +**前提**: Task 5 完了後 +**Steps:** +- [ ] 新シナリオ1件を v6 で実行し、Javadoc 知識ファイルが参照されること・正答することを確認する +- [ ] v6 既存シナリオのベンチマークを実行し、ベースライン（95.9%）から低下がないことを確認する（逐次実行） +- [ ] 問題があれば Task 3〜5 に戻って修正する - [ ] 結果を `.work/00363/notes.md` に記録する -### Task 5: 全バージョン適用（v5 / v1.4 / v1.3 / v1.2） +### Task 7: 全バージョン適用（v5 / v1.4 / v1.3 / v1.2） **Goal**: SC「all 5 versions」を満たす。 -**前提**: Task 4（v6 検証 OK）後 +**前提**: Task 6（v6 検証 OK）後 **Steps:** -- [ ] mappings/v5.json, v1.4.json, v1.3.json, v1.2.json に `api/` カテゴリエントリを追加 +- [ ] Task 2 の設計書を全バージョン向けに適用する（mappings/v5.json 等） - [ ] 各バージョンで jarツールを実行して Javadoc MD を生成する - [ ] `rbkc.sh create && rbkc.sh verify ` を全4バージョンで実行し FAIL 増加なしを確認 - [ ] 全バージョンのベンチマークを実行し、スコア低下なしを確認（逐次実行） -### Task 6: 差分チェック + PR レビュー依頼 -**Goal**: 全タスク完了後、変更差分が想定どおりかをチェックしてレビュー依頼。 -**前提**: Task 5 完了後 +### Task 8: 差分チェック + PR レビュー依頼 +**Goal**: 変更差分が想定どおりかをチェックしてレビュー依頼。 +**前提**: Task 7 完了後 **Steps:** -- [ ] `git diff main...HEAD --stat` で変更ファイル一覧を確認する -- [ ] 想定外の変更がないかを全件チェックし、`.work/00363/diff-check.md` に記録する +- [ ] `git diff main...HEAD --stat` で変更ファイル一覧を全件確認する +- [ ] 想定外の変更がないかをチェックし、`.work/00363/diff-check.md` に記録する - [ ] ユーザーに確認を依頼する - [ ] Expert review を実行する（Software Engineer + QA Engineer） -- [ ] `/pr create` でPRを更新する +- [ ] PR を更新する --- From 4923c83a3e5103bfed433247eed6a19a13a7c45d Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 29 May 2026 16:21:58 +0900 Subject: [PATCH 4/5] =?UTF-8?q?docs:=20update=20tasks.md=20=E2=80=94=20def?= =?UTF-8?q?er=20implementation=20tasks=20until=20design=20approved=20(#363?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .work/00363/tasks.md | 83 +++++++++----------------------------------- 1 file changed, 16 insertions(+), 67 deletions(-) diff --git a/.work/00363/tasks.md b/.work/00363/tasks.md index 5392480e5..e6eda012f 100644 --- a/.work/00363/tasks.md +++ b/.work/00363/tasks.md @@ -7,40 +7,15 @@ ## Rules (applied to every task) - 1コミット = 1タスク（粒度を守る） -- SCを満たすようタスクを分割し、このファイルで管理する - 推測せず事実ベースで調査・作業・判断する（実物・全件を確認し、確認範囲を明示する） -- 既存の RST/MD/xlsx パイプラインへの変更は最小限 - RBKCのcreate/verifyを変更する場合は実装前に設計書を更新してユーザーに確認する - PRレビュー依頼前に、変更差分が想定どおりの変更のみかをチェックし、結果を作業記録に出力してユーザーに確認する -- 全タスク共通: 変更差分チェック → ユーザー確認 → PRレビュー依頼の順を守る - ---- - -## 背景・設計理解 - -### 問題の本質 - -RST内の `:java:extdoc:` (nablarch.* 751件) が現在は表示テキストのみに変換されリンクが消える。 -Javadocの詳細（メソッド・引数・戻り値・挙動）が知識ファイルに存在しない。 - -### あるべき姿 - -``` -jarツール → Javadoc MD → RBKC → api/ カテゴリの知識JSON + 閲覧用MD - ↑ -RST :java:extdoc: → 内部クロスドキュメントリンク（外部URL依存なし） -``` - -- キーワード検索・意味検索の両方から Javadoc 知識ファイルが参照される -- 閲覧用MDもクリッカブルなリンクになる -- 外部 `nablarch.github.io` Javadoc URL依存が消える --- ## Not Started ### Task 1: jarツール確認（入出力形式） -**Goal**: SC「Identify the input/output format of the provided jar tool」を満たす。 **前提**: ユーザーからjarファイル入手後 **Steps:** - [ ] jarツールを実際に実行してサンプル出力（MD）を取得する @@ -49,64 +24,38 @@ RST :java:extdoc: → 内部クロスドキュメントリンク（外部URL依 - [ ] 調査結果を `.work/00363/notes.md` に記録する ### Task 2: 設計書更新 → ユーザー承認 -**Goal**: 実装前に設計を確定する。jarツール出力形式を踏まえて以下を更新。 **前提**: Task 1 完了後 -**更新対象設計書:** -- [ ] `tools/rbkc/docs/rbkc-converter-design.md` — Javadoc MD → 知識JSONの変換ルール、`:java:extdoc:` 内部リンク出力ルール -- [ ] `tools/rbkc/docs/rbkc-json-schema-design.md` — `api/` カテゴリのJSONスキーマ -- [ ] `.claude/skills/nabledge-6/workflows/semantic-search.md` — `api/` カテゴリの扱い（分離 or 混在） -- [ ] `.claude/skills/nabledge-6/workflows/qa.md` — Javadoc質問への対応 +**Steps:** +- [ ] 設計書を更新する（Task 1の結果を踏まえて対象設計書・変更内容を確定する） - [ ] コミット・プッシュしてユーザーに確認を依頼する - [ ] ユーザー承認後に Task 3 へ進む -### Task 3: コンバータ実装 -**Goal**: Javadoc MDを知識JSON/閲覧用MDに変換し、`:java:extdoc:` が内部リンクになること。 -**前提**: Task 2 完了後 -**Steps:** -- [ ] `tools/rbkc/scripts/create/converters/javadoc.py` を新規作成（TDD: テスト先行） -- [ ] `rst_ast_visitor.py` の `:java:extdoc:` 処理を内部リンク出力に変更（対応JSONが存在すれば内部リンク、なければ表示テキスト） -- [ ] `mappings/v6.json` に `api/` カテゴリエントリを追加 -- [ ] `scan_sources()` / `_converter_for()` に javadoc フォーマットの分岐を追加 -- [ ] `rbkc.sh create 6 && rbkc.sh verify 6` を実行し FAIL 増加なしを確認 -- [ ] 全既存テストが通ることを確認: `pytest tools/rbkc/tests/ -x` +### Task 3: 実装タスク（設計承認後に確定） -### Task 4: 検索修正 -**Goal**: 意味検索・QAワークフローから Javadoc 知識ファイルが参照されること。 -**前提**: Task 3 完了後（index.mdにapi/エントリが生成されていること） -**Steps:** -- [ ] `workflows/semantic-search.md` を設計通りに更新 -- [ ] `workflows/qa.md` を設計通りに更新 -- [ ] キーワード検索: スキャン対象に自動追加されていることを確認（変更不要なら記録） - -### Task 5: ベンチマークシナリオ追加 -**Goal**: Javadoc参照質問に答えられることを検証するシナリオを用意する。 -**前提**: Task 4 完了後 +### Task 4: ベンチマークシナリオ追加 +**前提**: Task 3 完了後 **Steps:** - [ ] 既存シナリオでは Javadoc 知識ファイルが参照されないことを確認する -- [ ] Javadoc参照質問のシナリオを新規追加する（例: 「`UniversalDao#exist` の戻り値・挙動は？」） +- [ ] Javadoc参照質問のシナリオを新規追加する - [ ] 期待値（expectations）を設定する -### Task 6: v6 検証（新シナリオ1件 → 既存スコア確認） -**Goal**: SC「nabledge can correctly answer questions about Javadoc-deferred API details」「Benchmark scores do not decrease」をv6で確認する。 -**前提**: Task 5 完了後 +### Task 5: v6 検証（新シナリオ1件 → 既存スコア確認） +**前提**: Task 4 完了後 **Steps:** -- [ ] 新シナリオ1件を v6 で実行し、Javadoc 知識ファイルが参照されること・正答することを確認する -- [ ] v6 既存シナリオのベンチマークを実行し、ベースライン（95.9%）から低下がないことを確認する（逐次実行） -- [ ] 問題があれば Task 3〜5 に戻って修正する +- [ ] 新シナリオ1件を v6 で実行し、正答することを確認する +- [ ] v6 既存シナリオのベンチマークを実行し、スコア低下なしを確認する（逐次実行） +- [ ] 問題があれば Task 3 に戻って修正する - [ ] 結果を `.work/00363/notes.md` に記録する -### Task 7: 全バージョン適用（v5 / v1.4 / v1.3 / v1.2） -**Goal**: SC「all 5 versions」を満たす。 -**前提**: Task 6（v6 検証 OK）後 +### Task 6: 全バージョン適用（v5 / v1.4 / v1.3 / v1.2） +**前提**: Task 5（v6 検証 OK）後 **Steps:** -- [ ] Task 2 の設計書を全バージョン向けに適用する（mappings/v5.json 等） -- [ ] 各バージョンで jarツールを実行して Javadoc MD を生成する +- [ ] 全4バージョンに実装・設定を適用する - [ ] `rbkc.sh create && rbkc.sh verify ` を全4バージョンで実行し FAIL 増加なしを確認 - [ ] 全バージョンのベンチマークを実行し、スコア低下なしを確認（逐次実行） -### Task 8: 差分チェック + PR レビュー依頼 -**Goal**: 変更差分が想定どおりかをチェックしてレビュー依頼。 -**前提**: Task 7 完了後 +### Task 7: 差分チェック + PR レビュー依頼 +**前提**: Task 6 完了後 **Steps:** - [ ] `git diff main...HEAD --stat` で変更ファイル一覧を全件確認する - [ ] 想定外の変更がないかをチェックし、`.work/00363/diff-check.md` に記録する From 29cade80d5d4b8d521136687fa47d96c1ef70d93 Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 29 May 2026 16:26:50 +0900 Subject: [PATCH 5/5] docs: move investigation findings to tasks.md, remove notes.md (#363) Co-Authored-By: Claude Sonnet 4.6 --- .work/00363/notes.md | 33 --------------------------------- .work/00363/tasks.md | 30 ++++++++++++++++++++++++++++-- 2 files changed, 28 insertions(+), 35 deletions(-) delete mode 100644 .work/00363/notes.md diff --git a/.work/00363/notes.md b/.work/00363/notes.md deleted file mode 100644 index 06b743a28..000000000 --- a/.work/00363/notes.md +++ /dev/null @@ -1,33 +0,0 @@ -# Notes - -## 2026-05-29 - -### Issue #363 概要 - -Nablarch公式ドキュメントは詳細APIをJavadocに委ねているが、nabledge知識ファイルにJavadocが含まれていない。 -jarツールを使ってNablarchソースからMarkdownを生成し、RBKCパイプラインに追加する。 - -### 調査結果: RBKCパイプライン構造 - -- `rbkc.sh` → `scripts/run.py` の薄いシム。`create|update|delete|verify ` をサポート -- ソース: `.lw/nab-official/v{N}/` 配下の RST/MD/xlsx を `scan_sources()` でスキャン -- コンバータ: `converters/rst.py`, `converters/md.py`, `converters/xlsx_*.py`（フォーマット別） -- 出力: `.claude/skills/nabledge-{N}/knowledge/{type}/{category}/{file_id}.json` -- 現在、`:javadoc_url:` ロールはURLを捨てて表示テキストのみ残す（`rst_ast_visitor.py` L781-786） - -### 設計方針（暫定） - -**絶対制約: 既存の RST/MD/xlsx パイプラインに一切触れない** - -新フォーマット `javadoc` として追加のみ。変更対象は以下の追加のみ: -- `converters/javadoc.py` — 新規作成 -- `mappings/v*.json` — 新エントリ追加のみ -- `scan_sources()` — 新分岐追加（既存分岐に触れない） -- `_converter_for()` — 新分岐追加（既存分岐に触れない） - -→ jar の出力形式確認後（Task 0）に詳細設計を行う - -### 未解決事項 - -- jar ファイルの入手方法（issue に「実装時に提供」と記載） -- 各バージョンで対象クラスの範囲（全 public クラス vs. `:javadoc_url:` 参照のみ） diff --git a/.work/00363/tasks.md b/.work/00363/tasks.md index e6eda012f..5043c3424 100644 --- a/.work/00363/tasks.md +++ b/.work/00363/tasks.md @@ -13,6 +13,33 @@ --- +## 引継ぎ情報 + +### 問題の本質 + +RST内の `:java:extdoc:` がRBKCで表示テキストのみに変換されリンク・FQCNが消える。 +Javadocの詳細（メソッド・引数・戻り値・挙動）が知識ファイルに存在しない。 + +### 調査結果 + +- v6 RST内 `:java:extdoc:` 参照: 1,971件（うち nablarch.* 751件、638クラス） +- 知識JSONで「Javadoc」に言及しているファイル: 25件 +- Javadoc ベースURL: `https://nablarch.github.io/docs/6u3/publishedApi/` （conf.py `extlinks` で定義） +- `:java:extdoc:` の処理箇所: `tools/rbkc/scripts/common/rst_ast_visitor.py`（`java:extdoc` → 表示テキストのみ返す） + +### あるべき姿 + +``` +jarツール → Javadoc MD → RBKC → api/ カテゴリの知識JSON + 閲覧用MD + ↑ +RST :java:extdoc: → 内部クロスドキュメントリンク（外部URL依存なし） +``` + +- キーワード検索・意味検索の両方から Javadoc 知識ファイルが参照される +- 閲覧用MDもクリッカブルなリンクになる + +--- + ## Not Started ### Task 1: jarツール確認（入出力形式） @@ -21,7 +48,7 @@ - [ ] jarツールを実際に実行してサンプル出力（MD）を取得する - [ ] 出力MDの構造を全件確認する（クラス1つ分・複数クラス） - [ ] 入力形式（ソースファイルのパス指定・オプション）を確認する -- [ ] 調査結果を `.work/00363/notes.md` に記録する +- [ ] 結果をこのファイルの引継ぎ情報に追記する ### Task 2: 設計書更新 → ユーザー承認 **前提**: Task 1 完了後 @@ -45,7 +72,6 @@ - [ ] 新シナリオ1件を v6 で実行し、正答することを確認する - [ ] v6 既存シナリオのベンチマークを実行し、スコア低下なしを確認する（逐次実行） - [ ] 問題があれば Task 3 に戻って修正する -- [ ] 結果を `.work/00363/notes.md` に記録する ### Task 6: 全バージョン適用（v5 / v1.4 / v1.3 / v1.2） **前提**: Task 5（v6 検証 OK）後