NTFのドキュメント刷新 - #730
Draft
kiyohome wants to merge 163 commits into
Draft
Conversation
抽出単位をL3のみとしていたため、L3を持たないページ全体（RST47中16 ファイル）と、L3配下に属さないL2/L1直下の本文が抽出対象外になって いた。 見出し階層のどこにも属さない本文が発生しないようルールを変更し、 L3を持たないL2はそのL2自体を、直下本文は (L2直下) / (L1直下)、 最初の見出しより前は (冒頭) として独立セクションに切り出す。 取りこぼしゼロを機械的に証明するため verify_coverage.py を追加し、 全行を counted / trailing_blank / heading / gap_blank に排他分類して 未説明の非空行が0件であることを検証する。build_mapping.sh から 自動実行するため、以降の回帰は検出される。 lines合計: current 7,318→9,211、input 2,494→3,011 セクション0件のRSTファイル: 16→0 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
レビュー指摘への対応。 lines の定義を「本文開始行から次のセクション開始行の直前までの全行 数」に変更し、末尾空行を除く処理を廃止した。lines がカバー範囲その ものになったため、外部から範囲を再構築できる。 カバー範囲を推測させないよう body_start_line / body_end_line 列を CSVに追加した。指摘の誤検出は範囲を [src_line, src_line+lines-1] と 解釈したことで生じており、src_line は見出し行を指すため本文とは2行 ずれる。列として明示することで再発しない。 verify_coverage.py の検証方法をバケット分類の恒等式から行番号の集合 演算に変更した。covered = セクション範囲の和集合、uncovered = 全行 − covered を直接求め、見出し行を除いて残った行を内容付きで列挙する。 分類の正しさに依存しない。sum(lines) == covered で範囲の重複も封じた。 結果: 非空行の未カバーは current/input とも0件。空行のみ 49/19 行が 残り、checks/task-02a.md に全件列挙した。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
#2a の完了でセクション抽出の実態が判明した（current 377セクション 9,783行、100行超が23件で全体の36%、最大314行。input は最大63行）。 マッピング作成の前に分割位置を確定させる #4a「大きいセクションの分割 判断」を新設した。対象は sections-current.csv の lines >= 100 の23件。 分割しない判断にも内容に基づく根拠を求める。 #5 を改訂した。mapping.csv に src_section_id / src_body_start / src_body_end を追加し、lines を担当範囲の行数と定義した。取りこぼし 検証を行範囲の集合演算で行い、verify_mapping.py としてコミットする。 579セクションを1コンテキストで処理すると判断がぶれるため、出典ファイル 単位でサブエージェントに分担させる。 あわせて作業指示書のタスク番号を steering と揃え（#1 作業指示の受領、 #2a、#4a を反映）、#2 の出力列と出典参照を実装後の実態に更新した。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
lines 合計 12,986 の一致は DROP 行を残す限り必ず成立するため、 取りこぼしがないことの確認にはなるが、全量が新構成に移ったことの 証明にはならない。DROP を乱用しても検証が通ってしまう。 mapping.csv には追跡可能性のため DROP 行も残したうえで、DROP を 除いた lines 合計を volume.md に記載し、verify_mapping.py が両方の 数値を並べて出力するよう完了条件を改めた。DROP 分の行数が可視化 されていれば、想定外に多い場合に気づける。 volume.md には DROP の合計行数と note の理由別内訳も残す。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- mapping/glossary.md: 9カテゴリ・正表記73語。正表記/意味/揺れ表記(file:line)/採用根拠を記載 - mapping/tools/detect_term_variants.py: discover(punct/paren/longvowel)とscanの2モード - mapping/tools/term_candidates.tsv: scanの用語定義(133エントリ) - mapping/tools/test_detect_term_variants.py: 34テスト 現行解説書のfile:lineはdevelopとのmerge-base時点の内容、FW解説書・input資料は 作業ツリーの行番号。glossary.md内の219件のfile:line参照は全件を実ファイルに 突き合わせて確認した。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
網羅性: - 「精査」を裁定し §5.6 バリデーションを新設（精査→バリデーション、 項目間精査→相関バリデーション、単項目精査→単項目バリデーション） - 骨格語（テストクラス/テストメソッド/テストケース/ハンドラキュー）を掲載し、 掲載基準を「揺れが検出されたか」から切り離す - YAML側の単位語を立項し、Excel/YAML の粒度をそろえた対応表を §5.9 に追加 - テストショット・リクエスト ID・単体テストの略称群・稼動環境を裁定 事実誤り: - 「編」を持つFW見出しは6件、FW グループID 22件中3件は認可機能、 scan の行順は用語定義ファイル順、現行解説書の NTF は2件、 使用方法の独立見出しは36件、JUnit5 は toctree のファイル名、 単体テストの単独用法は8件 — いずれも実測に合わせて訂正 設計: - HTTPメッセージ送信/受信の正表記をFW解説書に合わせて確定し未解決事項#4を解消 - 記述様式（括弧・空白・送り仮名）を nablarch#4 style.md の管轄とし実測を申し送り - §8 対応表に適用条件列を新設し全87行に条件を記載 - データブロック/データタイプ/グループIDの循環定義を解消 - 揺れ表記と別義・旧名称を列で分離 検証: - verify_glossary.py を追加（参照・件数・§5と§8の整合・tsvとの整合・適用条件） - 基準コミットを定数で固定し出力に刻む - match_line を真の最長一致に修正（件数の変化5件） - discover に spacing ルールを追加し散文の空白の揺れを検出 - コーパス取得層のテストを追加（カバレッジ 0% → 98%） Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- モックアップクラス・複数レコードレイアウト・エンティティバリデーションを 新規掲載し、出典不明だった「マルチレイアウト」を実在表記に置換 - 誤った file:line 引用（メッセージング処理の根拠行、セルの代表引用）を修正 - YAML形式の採用根拠をdesign.mdの実際の出典に基づく記述に訂正 - 単体テスト単独用法の脚注の過度な一般化を撤回し8件を個別に記述 - 同期応答メッセージ送信・HTTPメッセージ送信の語順違いの表記揺れ （メッセージ同期送信処理等）をterm_candidates.tsvに追加しscan-terms.tsvを再生成 - 250字超の長大セルを4件短縮し、部分文字列衝突の検出限界を§4に追記 - 「現行NTF解説書」の表記を「現行解説書」に統一 - checks/task-03.mdのSelf-check/Evidence列に対応内容と実測根拠を記録 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
ラウンド1〜3のレビュー指摘（G-1, G-2, G-5, G-9, G-10）は用語集に対象母集合が 未定義であることが共通原因だったため、term-candidates.csv による機械抽出・ 突合と、個別の記述ミス（G-4, G-6, G-7, G-8）修正をタスク#3に追加し、ラウンド カウントをリセットする。steering.md の State はプレースホルダにリセット。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
用語集の3ラウンドのレビューがいずれも新しい抜けを指摘し続けたのは、 用語集が対象とする用語の母集合を定義していなかったため。現行解説書の 見出し（sections-current.csvのheading_path）・input/ntf-doc-terms.mdの 見出し・design.mdの見出しと処理方式名の4出典から339行・331種類の 候補を機械抽出し、term-candidates.csvに出力する。 current-heading候補のfile:lineは、子見出しを持つ見出しがsections- current.csv上に自分自身のセクション行を持たないため、基準コミット 時点の.rstを再パースして見出し自身の行番号を求める（heading_pathの 該当行のsrc_lineをそのまま使うと無関係な行を指す誤引用になるため）。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
mapping/glossary.md に §5.15「term-candidates.csv との対応（母集団の 全件判定）」を新設し、339行・331種類の候補全件を採用（36件、既存の §5用語への相互参照）または不採用（295件、候補ごとの具体的理由付き） に判定した。design.mdの章・セクション見出し21件・input見出し39件・ 現行解説書見出し236件のいずれも、掲載基準に照らした理由を個別に記す。 verify_glossary.pyに population/design_sections/scheme_names/reasons の4検査を追加（既存のrefs/counts/sections/terms/appliesは維持、計9 検査）。term-candidates.csvの全件が採用/不採用のいずれかに対応し 未判定0件であること、design.mdの章・セクション名がすべてglossary.md に存在すること、処理方式名がdesign.mdの正式名称と一致することを機械 検証する。test_verify_glossary.pyに15件のテストを先行追加した。 あわせて母集団とは別の記述ミス4件を監査・修正した。 - 150字超の表セル41個を実測で特定し、全件150字以内に短縮 - 採用根拠の引用124件・件数主張約250件を再検証（既存記述に不一致 なし。短縮作業中に自己混入させた不一致は同作業内で復元） - §9の判定語「一部不採用」のうち、不採用要素が実際には無い1行を 「表記変更」に訂正 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
extract_terms.py / term-candidates.csv / glossary.md §5.15 / verify_glossary.py （9検査）/ G-4・G-6・G-7・G-8修正の実装7ステップを完了・独立検証済みとして check-off。残る4観点レビュー（ラウンド1）とuser reviewは未着手のためwip。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
用語集は全用語の網羅的な確定ではなく表記統一のための参照物とする方針転換を受け、 glossary.md §3の掲載基準を「表記揺れ確定用語」「design.mdの章・セクション名用語」の 2種類に限定し、§5.15は339候補中の非該当295件を候補ごとの理由なしで一括「今回は 判定しない」と記録する形に縮小した。verify_glossary.pyのpopulation/reasons検査を 「採用/不採用(理由付き)/一括判定」の3値に対応するよう更新し、揺れ表記のfile:line 根拠が欠けていた10行27箇所を補充、意味欄に残っていた旧表記(バッチ処理/ブック)を 正表記に修正した。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
design.md「7. トンマナ」が指定する8観点（文体・セクション構成・見出し形式・ アンダーライン記法・コードブロック・アドミニション・表の記法・:ref:ラベル）を、 ja/application_framework/application_framework/libraries/配下の複数.rstから file:line根拠付きで抽出した。#8以降のページ作成でCCが従う基準とする。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
FW解説書ライブラリの一般的な型（機能概要→モジュール一覧→使用方法→拡張例）を そのまま規約本文にしていたため、design.mdが決めた第2部・第3部のページ構成 （モジュール一覧を第1部の稼動環境に集約し、処理方式ごとのページには置かない） と矛盾していた。規約本文を design.md の決定に合わせて書き直し、根拠として design.md:34,48-52,76-88,132-141,143 を明記した。FW解説書の一般的な型の実例は 根拠として残しつつ、NTF解説書はモジュール一覧を除いた並び順のみを踏襲する旨を 明確にした。
nablarch#8〜のStepsに[セクション境界]/reference-only sections対応が既に記載済みであることを 確認。checks/task-05d.mdにSTEP8記録とself-check（全Completion criteria機械検証結果）を 追加。steering.mdの#5d Completion criteriaのうち「design.md/mapping.csv/_batch/*.csvに 差分がない」「591行/12,986/11,973が不変」は#5c差し戻し対応完了前の旧基準値のまま 更新されていなかったため、STEP7の意図（_batch/*.csv編集を明示指示）と#5cの確定値 （593行/12,986/11,983）に合わせて表現を修正した。design.mdおよびdest_page/disposition/ audienceに差分がないことは機械検証済み。
/rn:ty により#5c（差し戻し対応後）を承認、#5d（記録の整合とセクション境界の是正、 STEP1〜8）を完了。ユーザーによる#5dのuser review verdict待ちで中断する。
「4件誤検出」は実測と不一致。是正前にタプル比較を適用した場合の(L2直下) ERRORは4件（current-0150/current-0269/current-0049/current-0079）で、 うち誤検出はcurrent-0049/current-0079の2件のみ。dest_section単独比較へ 変更した判断自体は妥当であり変更しない。verify_mapping.py/mapping.csv/ design.mdは無変更。
②のYAML言及行集計を実測に訂正（方法により90〜206行、input側パス由来の部分一致 という方法論上の欠陥を明記）。③にPENDING_ZERO 26件の8分類仕分けと未処理2件 （RESTfulウェブサービス機能概要0件を含む第2部設定ページ10/8件、第3部取引単体 テスト小規模3ページの統合要否）を追加。④はファイルパスの省略記法をやめ全38ページ を1行ずつ対応付けた表で再提示。design.md/mapping.csvは無変更。
①稼動環境0件(案A)・②テストデータの形式廃止・③取引単体テストの設定3処理方式化、 未処理1(第2部機能概要/拡張例を任意化)・未処理2(第3部小規模ページ統合しない)・ 分類6(テストデータ2ページに機能概要適用)・分類7(current-0128分割方針)・ 分類8(テストデータ変換ツール導入なし)をdesign.md §2/3/4/5/6/8/11/12に反映し、 確定したファイル構成を新設§13として取り込んだ。判断根拠はchecks/task-06.md。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…を確定内容に合わせて更新 STEP2: _batch/*.csvを編集しmapping.csvを全30バッチ連結で再生成（593→594行）。 current-0180/0267を第1部稼動環境へ移動、input-0114を機能概要へ変更（分類6、実ファイル 通読で候補8件中1件のみ該当と判定）、current-0128を機能概要/使用方法にSPLIT（分類7）、 暫定27行の「暫定。」表記を確定理由に書き換え、vocabulary.mdを全34ページ確定に更新。 STEP3: verify_mapping.pyのSECTION_TEMPLATE第2部を使用方法のみに変更し、機能概要/ 拡張例0件はcheck_part2_optional_sections()のadvisory出力に移行。EXPECTED_ZERO_SECTIONS にテストデータ変換ツール導入・テストデータの記載例機能概要を追加、PENDING_ZEROを 26件から0件に解消。 STEP4: 検査でEXIT:0・PENDING_ZERO 0件・stale allowlist 0件・594行/12986/11983を確認、 volume.mdを再生成。 STEP5: checks/task-06-proposal.mdを削除し参照を書き換え。 STEP7: checks/task-06.mdに実施記録を追記、steering.md #6のチェックボックスを更新。 判断根拠と分類6の移した行・移さなかった行の対比はchecks/task-06.md参照。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
check_intro_section_splitのadvisory全件が[セクション境界]noteを持つことを 機械検査で担保する。#5dでは advisory 4件に個別追記したが、#6でadvisoryが 5件に増えた際にcurrent-0128-aへの追記漏れが発生したため、件数固定の運用を やめmapping_idから該当行のnoteを引く方式に変更した（RED確認: current-0128-a がERRORでexit 1になることを確認、checks/task-06-followup.md参照）。 配置先: .rn/20260724-ntf-yaml-support/ntf-doc-06-followup.md Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
対応1-1: current-0128-aのnoteに[セクション境界]を追記し、mapping.csvを _batch/*.csvの単純連結で再生成した（594行、EXIT:0のGREEN確認済み・ checks/task-06-followup.md参照）。対応1-4: nablarch#8〜のSteps確認は修正不要と確認。 対応2: checks/task-06.md:906のself-check文言をtask-06-proposal.md参照の 実態（9件、すべて削除済み旧ファイルの注記付き）に合わせて修正した。 steering.mdに#6レビュー指摘対応の実施記録を追記し、Stateをuser review待ちに更新。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
削除前に対象47件（パス・行数）とtoctree/:doc:参照の現状をchecks/task-07.mdに 記録。画像・ダウンロード素材125件は無変更。steering.mdの#7 Stepsを更新。
削除した47ファイルの定義ラベル76件とja/削除ツリー外の:ref:参照2708件を 機械的に交差し、db_double_submit.rstからの被参照1件を検出。 checks/task-07.mdのリンク切れ参照を3件に更新し、nablarch#8〜・#lastに ラベル再定義・解消確認のStepを追加。.rstの削除・復元やmapping.csvの変更は行わない。
CIが無くja/conf.pyのkeep_warnings=Trueのため、未解決の:ref:/toctree参照は make htmlのエラーにならず素通りする。#lastのStepsを、エラー0の確認から undefined label/toctree contains reference to nonexisting document/ unknown documentが警告ログに0件であることの確認に書き換え、 checks/task-07.mdの3件の解消後参照先を記録するStepを追加。 ja/conf.py・design.md・mapping.csv・.rstは無変更。
ユーザー指示「再開後に進めて」によりrn:up時は確認を挟まずnablarch#8〜に着手する旨をNextに記録。
mapping.csvのdest_page=テスティングフレームワークとはの13行(current-0162/163/164/165/166/175/176/180/267/377, input-0002/116/028)を根拠に about/index.rstを新規作成。全体像/アーキテクチャ/テストの種類/テストデータ/対象範囲/稼動環境の6節構成。 最上位index.rstは読者振り分け文とabout/indexのみのtoctreeを持つハブページとして新設。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- アーキテクチャ構成図（abstract_structure.png）を追加し、表をsimple tableに変換 - データブロックの考え方を修正し、データタイプ/グループIDの関係とデータブロックの識別方法（種別+識別子の値、14種）を両方正しく記載 - 処理方式ごとの正式名称テーブルをdesign.md記載の6処理方式名に合わせて修正 - テストデータ外部化・テストの独立性・マスタデータ投入tip・マルチスレッドimportantの逐語的な記述を書き直し - 稼動環境セクションにラベルを追加し、全体像からの参照を:ref:化
- テストの独立性: マスタデータ外部化のタイミングと3メリットの脱落を復元 - データブロックの考え方: セル値解釈規則の並列列挙からコメントの脱落を復元 - 処理方式ごとの正式名称: 同期応答メッセージ送信処理の事実をMOM行に統合復元、HTTPメッセージング行・テーブルをキュー行の内容を出典に即して修正 - 逐語的な表現が残っていた5箇所を主語・節順・文境界を変えて書き直し - データブロックの考え方の用途/内容/主なデータタイプ表をlist-tableからsimple tableに変換
観点B（トンマナ）の「逐語的流用」判定基準を主観的表現から具体的な 判定条件（指摘してよい/しない）に置き換え、指摘時は出典と成果物を 並べて引用することを必須化。観点Dに見出し・導入文と実物の中身の 一致をチェック項目として追加。指摘の重大度をmust/decide/noteの 3区分で定義し、3ラウンド上限でユーザーレビューに上げてよいのは decideのみとし、mustは必ずラウンド内で解消する運用に変更。 #8のレビュー実施結果、未解決5件中3件が過剰指摘、実在する不整合 1件を見逃していたため（ntf-doc-08-rework.md参照）。
見出し「処理方式ごとの正式名称」と導入文が表の中身（クラス単体・ 取引単体テストを含む）と食い違っていたため「テスト種別の正式名称」 に修正し、導入文を実際の中身に合わせた。glossary.mdにない造語 「同期応答電文」を正表記「同期応答メッセージ送信」に修正。 mapping.csvに出典のない「テーブルをキューとして使ったメッセージング」 行はA-3の判断により削除し、表をsimple table化した。 是正後の観点B/C/D基準で独立サブエージェントによる再レビューを 3ラウンド実施し、見つかったmust指摘（テストデータ外部化冒頭文・ 対象範囲のimportant2件・データブロックの考え方1文の逐語的流用、 見出しと処理方式一覧の不整合）を解消。新基準の機械適用がユーザー 既承認のA-5対象（R3-B2/B3相当）を再度must判定した箇所は、 ユーザー判定を優先し原文へ差し戻した。 「対象範囲」節にdesign.md §2が求める処理方式一覧を追加しかけたが mapping.csvに出典がないため取り消し、decide案件としてユーザー 判断へ回した（reviews/page-about_index.md参照）。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
出典（現行解説書・input資料）とdesign.mdの確定設計が食い違う場合に確定設計を 優先する旨をdesign.md §8に追記し、§11.7のmust定義にvocabulary.md/design.mdとの 不一致を追加した。観点A・観点Dのレビュープロンプト（ntf-doc-rebuild-instruction.md） にも同趣旨のチェック項目を加え、#9以降で同種の誤判断（nablarch#8 A-3のようにvocabulary.md のページ名を出典不在を理由に落とす判断）が繰り返されないようにした。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
design.md §2の「対象範囲」を対応しないものの明示に限定し、「対応する処理方式の 一覧」の責務を「テストの種類」節（テスト種別の正式名称の索引）に一本化した。 一覧が2箇所にあると処理方式の増減時に片方が古くなるため。 これに伴いnablarch#8 A-3で「マッピングにない内容」として削除したリクエスト単体テスト （テーブルをキューとして使ったメッセージング）行の判断を覆し、正式名称表へ 復元した。vocabulary.md:74に第3部の生きたページ名として存在する以上、本文書の 名称索引にその名前が無いのは不整合であり、出典input-0028が6区分時代の資料で 当該行を持たないことは行を落とす根拠にならない（design.md §8「出典と確定設計が 食い違う場合」参照）。about/index.rstに:refラベルを新設し、対象範囲から 1文の導線で参照させることで一覧の再掲を避けた。 新基準での独立サブエージェント4観点の再レビューで、行復元により表が処理方式を 網羅した結果、導入文の「主な」が非網羅時代の名残として矛盾を起こしていたのを 検出・修正（must 1件、ラウンド2で解消・must残存なし）。verify_mapping.pyは exit 0で594行/12,986/11,983行が不変、Sphinxビルドも本ページ由来のエラー・ 警告0件を確認。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
STEP1（710a1af）・STEP2〜4（36deb4b）の完了を反映し、#8のuser review欄と State欄（Last completed/Next/Notes）を更新した。次はcommit SHA 710a1af・ 36deb4bの独立検証待ち。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
See steering.md