diff --git a/docs/adr/adr-007-custom-linter-layer-boundary.md b/docs/adr/adr-007-custom-linter-layer-boundary.md index 681e93e..aaf3680 100644 --- a/docs/adr/adr-007-custom-linter-layer-boundary.md +++ b/docs/adr/adr-007-custom-linter-layer-boundary.md @@ -75,3 +75,34 @@ Q3. パターンはリテラル文字列のマッチのみで表現できるか - 正規表現層は「シンプルで速い」、AST 層は「正確だが遅い」という責務分離が維持される - 将来 ast-grep を導入する際、既存の正規表現ルールを移行する必要がない（責務が明確に分かれているため） - `regex` crate 追加による exe サイズ増加は約 200KB 程度（許容範囲） + +## Amendment (2026-05-17, PR #140 由来) + +PR #140 のルール⑧ (`no-docs-relative-back-to-docs`) で「`paths` filter 未適用のまま pattern semantics で自己限定する」設計を採用した経験から、以下 2 項目を追記する。 + +### Semantic self-limitation の安全条件 vs explicit `paths` filter 必須条件 + +正規表現層のルールでスコープを絞る手段は 2 通りある: + +1. **Semantic self-limitation**: pattern 自身が path-context を含意し、対象外ファイルでは false positive を発生させない +2. **Explicit `paths` filter**: `paths = ["docs/**/*.md"]` 等で対象ファイルを明示的に限定 + +判断基準: + +| 条件 | 推奨手法 | 例 | +|------|---------|-----| +| pattern が path-context を含意する（対象外ファイルでは自然な記述形式と区別される） | Semantic self-limitation で OK | ルール⑧ の `DOTDOT/docs/` 形式 = parent-dir 経由で `docs/` を再参照するため、`docs/` 配下以外では自然に出現しない | +| pattern が path-agnostic（対象外ファイルでも頻出し、特定スコープに限定したい） | Explicit `paths` filter 必須 | `eprintln!` は src/ 全体で頻出、特定 crate のみに限定したい場合 | +| 対象外ファイルで意図的に fire させたい（true positive として扱う設計） | `paths` filter 適用は避ける | ルール⑧ の root-level MD (CLAUDE.md / README.md) からの参照は true positive 扱い | + +**判断 flow**: pattern を grep で実測し、対象外ファイルでの false positive 比率が低水準（目安: 数 % 以下）に収まるなら semantic self-limitation で OK、超えるなら `paths` filter 必須。**迷ったら `paths` filter に寄せる**（AST 層への寄せと同方針）。 + +### Lint rule 最小テストチェックリスト + +新規 lint rule 追加時の必須テスト構成: + +1. **Pattern detection test**: 想定するアンチパターン入力で fire することを確認（rule が機能する基本契約） +2. **Case-insensitive test** (該当する場合): pattern に `(?i)` を含めるなら、大文字バリアント / 小文字バリアントの双方で fire することを確認（PR #91 の PowerShell `(?i)` 教訓 = case-insensitive 宣言と実テストの乖離を防止） +3. **False positive skip test**: 似て非なる正当パターンで fire しないことを確認（semantic self-limitation を採用したルールではこのテストが scope 契約を担保する） + +3 項目を最低水準とし、ルールごとに追加の boundary test（UTF-8 マルチバイト境界、複数行 / 単一行等）を加える。 diff --git a/docs/claude-code-web-tasks.md b/docs/claude-code-web-tasks.md index 9e3bda8..9a997b3 100644 --- a/docs/claude-code-web-tasks.md +++ b/docs/claude-code-web-tasks.md @@ -16,7 +16,6 @@ | 順位 | Tier | 内容 | 編集ファイル | 工数 | |---|---|---|---|---| -| 104 | T3 | ADR-007 amendment: semantic self-limitation 安全条件 + lint rule 最小テストチェックリスト (pattern detection / case-insensitive / false positive skip の 3 項目) (PR #140 T3-#1) | [docs/adr/adr-007-custom-linter-layer-boundary.md](adr/adr-007-custom-linter-layer-boundary.md) | S | | 116 | T3 | ADR-040 `step_timeout` 説明に sublinear / KV cache locality clarification を 2-3 行追記し、reference table 600s と formula 720s の数値整合化 (PR #145 T3-#1) | [docs/adr/adr-040-local-llm-context-size.md](adr/adr-040-local-llm-context-size.md) | XS | | 120 | T3 | `takt-workflow-persona-without-model` rule コメント拡張（field 拡張手順 4-5 行）+ ADR-007 case study 追記（enumeration-based 正規表現層、Rust regex lookahead 非対応の pragmatic 対処）(PR #150 T1-#1、実体 Tier 3) | [.claude/custom-lint-rules.toml](../.claude/custom-lint-rules.toml) ルール⑨ + [docs/adr/adr-007-custom-linter-layer-boundary.md](adr/adr-007-custom-linter-layer-boundary.md) | XS | | 127 | T3 | extensions 拡張時の test 追加 pattern を Rust ソース内コメントで明文化 (PR #151 T3-#2、順位 124 と同 PR 推奨) | Rust ソース内コメント（test location を正確に参照） | XS | diff --git a/docs/todo-summary.md b/docs/todo-summary.md index ab8e3b5..9c41e23 100644 --- a/docs/todo-summary.md +++ b/docs/todo-summary.md @@ -60,7 +60,6 @@ | 96 | 🔧 Tier 2 | **Markdown cross-reference validator CI step (PR #133 T2-#3 採用) ★ Bundle j** | todo6.md | M | 順位 10 (ADR-032 PR-broken-link) と方向性が近接、fold-in 検討の余地あり。順位 94 (regex 規約) + 順位 95 (count 照合) と組み合わせて docs/ 整合性の多層検証 | | 97 | 🔧 Tier 2 | **`with_num_ctx(X)` override 値 serialization 検証テスト (PR #136 T2-#1 採用)** | todo6.md | S | なし (PR #136 で追加した builder method の wiring を mockito で seal、Phase d で num_ctx tweak する局面の silent degrade 防止、CodeRabbit が見逃した test gap を post-merge-feedback agent が独立発見) | | 100 | 💎 Tier 3 | **`development-workflow.md` に 「同一ファイル複数編集の 1 task 統合」 + 「partial completion + 後続 PR 追補明記」 を追補 (PR #139 T3-#1 採用)** | todo6.md | XS | なし (PR #119/#120/#121 sub-PR 分割 + PR #139 partial completion で systemic に観測された 2 暗黙知を `~/.claude/rules/common/development-workflow.md` に codify、`feedback_no_unenforced_rules.md` 例外 = 既存実践の明文化のため非機械強制でも採用相当) | -| 104 | 💎 Tier 3 | **ADR-007 amendment: semantic self-limitation 安全条件 + lint rule 最小テストチェックリスト (PR #140 T3-#1 採用)** | todo6.md | S | なし (rule⑧ で `paths` filter 不在を pattern semantics で代替した判断の rationale を ADR-007 に追記。「semantic self-limitation OK な条件」と「explicit `paths` filter 必須な条件」、lint rule 最小テストチェックリスト = pattern detection / case-insensitive / false positive skip の 3 項目最低化、3 ソース観測) | | 105 | 💎 Tier 3 | **グローバル CLAUDE.md に lint runner サポートフィールド一覧表 (PR #140 T3-#2 採用)** | todo6.md | XS | なし (`~/.claude/CLAUDE.md` に `pattern` / `extensions` / `severity` (planned: `paths`) の field 一覧を表形式で追加、派生プロジェクト (techbook-ledger / auto-review-fix-vc) で rule porting 時の理解統一、順位 103 の code comment と相補) | | 107 | 💎 Tier 3 | **`development-workflow.md` に PR #125→#141 anti-pattern 事例補強 (PR #141 T3-#2 採用)** | todo6.md | XS | なし (`~/.claude/rules/common/development-workflow.md` の「タスク完了削除手順」に「マージ後 N 日間 todo.md 残存 → 後続 phase で手動発見」事例を追記、memory `feedback_verify_task_not_already_done` を central rule にも反映、`feedback_todo_no_history` と合わせて「マージ → 即削除」サイクルを強調) | | 108 | 💎 Tier 3 | **CLAUDE.md に「Tier 2 偽装検知 + 却下パターン」table (PR #141 T3-#3 採用)** | todo6.md | S | なし (`~/.claude/CLAUDE.md` に memory `feedback_no_unenforced_rules` の policy をユーザー可視 table として公開、Tier 2 と称した必須化ルール提案を新セッションでも一貫して却下できる構造、memory ファイル閉鎖を補完) | diff --git a/docs/todo6.md b/docs/todo6.md index 79e50d1..ae9b8e7 100644 --- a/docs/todo6.md +++ b/docs/todo6.md @@ -279,46 +279,6 @@ config.rs + push-runner-config.toml + review-simplicity.md + ADR で family_tag --- -### ADR-007 amendment: semantic self-limitation 安全条件 + lint rule 最小テストチェックリスト (PR #140 T3-#1 採用) - -> **動機**: rule⑧ (PR #140) で `paths` filter 不在を pattern semantics で代替した判断は妥当だったが、**どんな条件下で semantic self-limitation が安全か** / **explicit filter が必須な条件は何か** が ADR-007 に明文化されていない。3 ソース (PR diff / prepush / session) でこの documentation 不足を独立指摘。同時に lint rule 最小テストチェックリスト (pattern detection / case-insensitive / false positive skip の 3 項目) も ADR レベルで確立すると future rule author の prior が安定化する。 -> -> **本タスクの位置づけ**: PR #140 post-merge-feedback Tier 3 #1 採用 (Severity Low / Frequency Low = 3 ソース観測 / Effort S / Adoption Risk None)。 -> -> **参照**: `.claude/feedback-reports/140.md` Tier 3 #1、`docs/adr/adr-007-custom-linter-layer-boundary.md`、PR #140 rule⑧ 設計判断 - -#### 追加する 2 section (ADR-007 への amendment) - -##### (a) Semantic self-limitation の安全条件 vs explicit filter 必須条件 - -- **OK**: pattern が path-context を含意する場合 (例: `](../docs/` は parent-dir 経由で docs/ を再参照 → docs/ 配下以外では自然な記述形式と区別される) -- **NG**: pattern が path-agnostic で paths filter 必須 (例: `eprintln!` は src/ 全体で頻出、特定 crate のみに限定したい場合は path filter が必要) -- **判断 flow chart**: 「pattern semantics で false positive が **動機**: 派生プロジェクト (techbook-ledger / auto-review-fix-vc 等) で hooks を porting する際、lint runner がサポートするフィールド (`pattern` / `extensions` / `severity` / `message` / `why`、planned: `paths`) を一目で把握できる reference が グローバル CLAUDE.md に存在しない。順位 103 (code comment) と相補的で、cross-project 可視性を即時向上。