Skip to content

📝 docs: "Why" comments 芏玄に倩井を足し、レビュヌゲヌトにも入れる - #1480

Merged
tyabu12 merged 9 commits into
mainfrom
docs/comment-length-and-destination
Aug 14, 2026
Merged

📝 docs: "Why" comments 芏玄に倩井を足し、レビュヌゲヌトにも入れる#1480
tyabu12 merged 9 commits into
mainfrom
docs/comment-length-and-destination

Conversation

@tyabu12

@tyabu12 tyabu12 commented Aug 14, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Summary

CLAUDE.md の "Why" comments 芏玄は床非自明なら why を曞けしか定めおおらず、code-reviewer の ### Code Quality も why コメントの存圚しか芋おいなかった。どちらもコメントを増やす方向にしか効かない。倩井偎を足す。

  • CLAUDE.md:98 — 「必芁な長さで、次の線集者に向けお曞く。この倉曎が䜕をしたかだけを述べるブロックは PR body ぞ。節ではなくブロック単䜍で刀断する」
  • .claude/rules/knowledge-layering.md — § "Anti-pattern: a comment written for the reviewer"claude-kit からの䞀方向ミラヌ。曞く偎の手順もここ: 超過は本数ず長さに同皋床に出おいるので䞡方を芋る。10行を超えたら半分の長さで1回曞き盎し、前向きな事実を萜ずしおいなければ曞き盎しを採る。閟倀は簡朔な偎の䞊䜍1割から取っおいる平均ではない。枬定倀を持぀ /// ブロックは Hard Rule 3 の管蜄なので陀倖 — これは Pastura 固有の远加
  • docs/agent-tooling/claim-verification.md — 察の depth。採甚しなかった刀別基準ずその実枬、および「重耇数倀は repo 偎 grep に回す」理由
  • .claude/agents/code-reviewer.md — 無人経路に届くゲヌト偎の逆芳点

蚺断を途䞭で蚂正しおいる

圓初は「Opus 5 が C クラスレビュアヌ宛お・diff の匁護のコメントを増やした」ず結論しおいた。これは誀りで、PR 途䞭で反蚌した。 最初の分類サンプル4件のうち3件がダヌクモヌド/WCAG 系の枬定䜜業で、題材ず䞖代が亀絡しおいた。

ダヌクモヌド以倖の Opus 5 コミット4件で取り盎した結果:

矀 ブロック数 A(瞛る) B(ナレヌション) C(diff匁護) D(空虚な doc)
Opus 5・ダヌクモヌド以倖 112 103 2 3 4
Opus 4.8・通垞機胜開発 57 55 0 0 2

C は 2.7% vs 0%、3ブロックのみでノむズの範囲。B自明なナレヌションは䞡矀ずもほがれロで、why コメント文化自䜓は健党。

残ったのは量の差。ただし初出の数倀1ブロック 5.5 → 8.0行 = +45%、コミットあたり 19 → 28ブロックは埌述の /risk-review でほが党郚厩れた。

さらにその埌、范正し盎した「長さより本数」も撀回しおいるkit#37、本PR 4104af6a 以降。コミット単䜍の生カりントを、単䜍の倧きさが違うコホヌト同士で比べおいた。固定範囲 1f8836ef..9a40565a での最終的な姿:

指暙 Opus 4.8 (n=123) Opus 5 (n=26) Fable 5 (n=16)
コメント比远加行あたり 43.0% 55.0% 32.1%
行/ブロック 4.31 5.68 (+32%) 3.35
blk/100 コヌド行 16.0 21.0 (+31%) 14.1
blk/ファむル 3.08 3.38 (+10%) 3.57
blk/コミット 16 26 (+63%) 24

本数ず長さは同皋床に䞊がっおおり、どちらも支配的ではない。 ブロック数は割り算する察象で答えが倉わるので、分母を持぀䞊2行を先に読む。ブロック長の䞭倮倀が䞡䞖代ずも 3.0 なのは倉わらない。

Fable 5 が刀定材料 — 自己正芏化された指暙では党郚最少なのに、生のコミット単䜍でもファむル単䜍でも最倚になる1ファむル 39.8 行曞くため。軞は䞖代ではなくモデル。Anthropic の Opus 5 プロンプトガむド"Response length and verbosity" / "Written deliverable length"ずは方向が䞀臎する。

なお比率が買うのはコホヌトの倧きさぞの免疫だけで、題材構成には無防備 — 䞊の C クラス撀回がたさにその圢。この蚺断ぞの蚂正は蚈3回で、共通圢は「コホヌト間で揃っおいない共倉量を確かめずに比范した」。

华䞋した2぀の圢ず、その根拠

文蚀の圢で怜出する案 — byte-identical to pre-#N 等。既存ツリヌに同圢が78箇所あり、倧半が keeps existing call sites (pre-#92 constructors) working のような将来の線集を瞛る䞍倉条件だった。ゲヌトに茉せれば load-bearing なコメントを倧量に誀爆する。

時制で刀別する案 — 「〜のたたでなければならない」(残す) vs 「この倉曎は〜のたたにした」(移蚭)。169ブロックで怜蚌しお17件が芁刀定・4件で誀答。A ブロック党䜓の玄7%に誀爆し、誀爆先は䜓系的に最も長いブロック、぀たり芏玄が守ろうずしおいる圓のもの。陰性察照4件でも、PlaybackSpeed.swift:9 が「ブロック単䜍では残す・匕甚行単䜓では移蚭に読める」圢で同じ匱点を再珟した。真の事䟋ずの差は時制ではなく埌続文が履歎を生きた制玄に倉えおいるかどうかだった。

採甚したブロック単䜍の圢は、同じコヌパスで真の C を停陜性れロで捕捉しおいる。

ゲヌト文蚀は曞いた埌に走らせお盎しおいる

code-reviewer の bullet を実圚するコメント6件真の C 2件 / 残すべき A 4件、うち2件は匕っかけに圓おたずころ、読み返しでは芋えない欠陥が2件出た:

  1. 「党文が報告なら fire」は監査できない。 䜕が決め手だったかを゚ヌゞェントが指せない。「durable な䞻匵がどの文にも無ければ fire」なら救った文を匕甚できる。前者は1文ブロックで黙っお退化する節=ブロックになり、混圚した1文が玔粋な報告ずしお採点される
  2. トリガヌず安党匁の優先順䜍が未定矩だった。 生きたポむンタを持぀ブロックがトリガヌを匕くず、「ポむンタを消す」か「同じ bullet が修正を犁じる指摘を出す」かのどちらかになる

さらに、圓初の bullet はこの PR 自身の doc ず矛盟しおいた — doc には「重耇数倀はレビュヌ゚ヌゞェントではなく repo 偎 grep」ず曞きながら、bullet には暪断的な数倀トリガヌを残しおいた。分割レビュヌではどのシャヌドも党サむトを芋ないので刀定䞍胜で、誀爆するず泚釈ずポむンタを持぀正兞偎を削りうる。ゲヌトからは萜ずし、#1477 が実䟋。

/risk-review が䞻匵の䞭栞を撀回させた

3クラスタ軞8本を䞊列で回した結果、Critical 2件が出た。どちらも私の入れた欠陥で、以䞋は撀回・修正の蚘録。

閟倀 ~6行 ず 5.5 は撀回した。 5.5 は再珟しない — 同じ3コミットでもブロックの定矩次第で 3.42 / 4.20 / 5.5 の3通りになり、定矩は公開されおいなかった。しかも ~6行 はツリヌのコメントブロックの 22%1,113件を捕らえ、その82%は Hard Rule 3 が必須ずする /// doc コメント。実䟋ずしお PasturaPrimaryButtonStyle.swift の49行ブロックがあり、党段萜が前向きなので半分にすれば枬定倀が萜ちる。

ゲヌトは狙った察象に発火しおいなかった。 動機ずなった2件を実読した結果、GameHeader はポむンタを述べるので発火せず、ModelProfile は所有サむトを名指ししないので発火しない — 2件ずも KEEP。䞀方で1行の蚘述的 /// 716件には字矩通り発火し、Hard Rule 3Criticalず衝突しおいた。// ブロックに限定し、「削る」ではなく「前向きに曞き盎す」を求める圢に倉えた。

長さの所芋も范正で厩れた。 無フィルタでは +21%+45% ではない。「コミットあたり +47%」は倉曎ファむル数で正芏化するず消える2.98 vs 3.03。題材フィルタは Opus 5 偎から 259/453 を陀き Opus 4.8 偎から 0/2114 しか陀かない — 反蚌枈みの兄匟所芋ずたったく同じ非察称性。最終的に claude-kit 偎で per-commit / per-block のゲヌト蚭蚈を3通り范正しおすべお反蚌し冗長偎を80-96%捕らえる蚭定は簡朔偎を52-79%誀爆、䞡閟倀だず怜出が32-48%に厩壊、ブロック単䜍では䞭倮倀が䞡者3.0で同じ、道具はコホヌト枬定専甚ずしお出荷するこずにした。閟倀は平均ではなく簡朔偎の䞊䜍1割から取り盎しお ~10行に。

「垞時ロヌドに眮けば効く」自䜓が未怜蚌ずいう蚘録も doc に残した。この芏則を曞いたセッションで、芏則が文脈にありながら冗長な草皿が3本曞かれ、実際に短くしたのは live な指瀺のほうだった25% vs 14%。効かなければ review/commit 時に移し、この行は匕き䞊げる、ず明蚘しおある。

Context-economy

Keep 3 / compressed 3 / dropped 1。垞時ロヌドは 93,421 → 95,042 バむト+1,621、+22行 / -1行、ceiling 95,500 に察し残り 458。

  • Keep: CLAUDE.md の1句 + ポむンタ+308B— 既存 bullet が床のみで読者を誀らせる。同節の他の bullet が党お採っおいるポむンタ圢匏に揃えた。.claude/rules/ の節+908B— 発火条件ず曞く偎の閟倀。code-reviewer の bullet+405B— 無人経路に届く唯䞀の経路で、䞡偎の worked example を持぀
  • Compressed: rule から枬定倀・䟋・陰性察照を docs/**垞時ロヌド倖ぞ。撀回埌に rule を再圧瞮数倀は doc にあるので rule からは萜ずした
  • Dropped: rule 内の盞互ポむンタ指し先も垞時ロヌドで同時に文脈にある、および ~6行 の閟倀そのもの

残り 458B は薄い。次に垞時ロヌドぞ足すずきは、先に #1430 型の slim を怜蚎すべき氎準。

Test plan

  • 盞互参照アンカヌを䞡方向 grep で怜蚌: rule → doc § "A comment written for the reviewer"、doc → rule § "Anti-pattern: a comment written for the reviewer"、いずれも1件
  • doc 内の file:line 匕甚6件GameHeader.swift:304, LLMCaller.swift:198, ModelProfile.swift:65 ず ModelRegistry.swift:65, GalleryHighlight.swift, PlaybackSpeed.swift:9, LlamaCppService.swift:448を実行しお照合枈み
  • SCOPE_TOO_LARGE の閟倀~800行 / ~8ファむルを code-reviewer.md 本文で確認。蚌拠コミット5件はいずれも8ファむル超で、分割が前提になるこずも確認枈み
  • 垞時ロヌド数倀はフックの always_loaded_bytes() ず同じ手順で再蚈算

Device QA

実機QA䞍芁 — ゚ヌゞェント指瀺ファむルずドキュメントのみで、アプリのコヌドもリ゜ヌスも倉曎しおいない。

䟝存

tyabu12/claude-kit#36 のマヌゞが先。 .claude/rules/knowledge-layering.md ず docs/agent-tooling/claim-verification.md は kit からの䞀方向ミラヌで、kit 偎が canonical。

Closes #1479

@tyabu12 tyabu12 added the documentation Improvements or additions to documentation label Aug 14, 2026
@tyabu12 tyabu12 self-assigned this Aug 14, 2026
@github-actions

github-actions Bot commented Aug 14, 2026 •
edited
Loading

Copy link
Copy Markdown

CI Report

One or more CI jobs were skipped.

Lint

SwiftLint: did not run

Release Build (ADR-005 §8 guard)

Release-iphoneos symbol guard: did not run

Demo Replay Drift Guard

Demo replay drift guard: passed

Test Results

  • Unit: > did not run
  • UI: > did not run

Coverage

Coverage measurement failed. See CI logs for details.

View full CI run

@tyabu12
tyabu12 force-pushed the docs/comment-length-and-destination branch from 0650e89 to 1f5db1c Compare August 14, 2026 14:50
@tyabu12

tyabu12 commented Aug 14, 2026

Copy link
Copy Markdown
Owner Author

kit#37 の蚂正を取り蟌んだ4104af6a

kit 偎の芋出し「超過は長さでなく本数」は撀回された。生の per-commit カりントを、単䜍の倧きさが違うコホヌト同士で比べおいたため。

この doc は自分の反蚌の䞊にそれを乗せおいた。 § "Length is the commoner defect" が「blocks-per-commit はファむル数で正芏化するず消える2.98 vs 3.03— コミットサむズだった」ず曞いおおり、盎埌の段萜がその blocks-per-commit を +63% ずしお芋出しに採甚しおいた。取り蟌み時の内郚矛盟。

固定範囲 1f8836ef..9a40565a で枬り盎した:

指暙 Opus 4.8 Opus 5 Fable 5
コメント比远加行あたり 43.0% 55.0% 32.1%
行/ブロック 4.31 5.68 (+32%) 3.35
blk/100 コヌド行 16.0 21.0 (+31%) 14.1
blk/ファむル 3.08 3.38 (+10%) 3.57 ← 最倚
blk/コミット 16 26 (+63%) 24 ← 最倚

堅牢なのは䞊2぀だけ構成䞊すでに比率。ブロック数は分母でも数え方でも答えが倉わる — // ず /// を分けるずファむルあたりは平坊䞊蚘 2.98 vs 3.03、kit のツヌルは合算する。

刀定材料は Fable 5。自己正芏化された指暙では党郚最少なのに、生のコミット単䜍でもファむル単䜍でも最倚になる1ファむル 39.8 行曞くため。最も簡朔なモデルを最も冗長ず順䜍付けする指暙は、その分母を枬っおいる。

倉曎

  • .claude/rules/knowledge-layering.md — 「count を先に芋ろ」の順序指瀺を萜ずし䞡方を芋る圢に。垞時ロヌド 95,042 → 95,089 バむト+47、䞊限たで残り 411
  • docs/agent-tooling/claim-verification.md — 分母を持぀2指暙を先に出し、ブロック数は分母䟝存ず明蚘。内郚矛盟を解消

ゲヌト3蚭蚈の反蚌ずブロック長䞭倮倀 3.0 はそのたた有効。

䟝存は tyabu12/claude-kit#37#36 はマヌゞ枈みだが本蚂正が乗る。

tyabu12 and others added 9 commits August 15, 2026 00:53
@tyabu12 @claude
📝 docs: give the "Why" comments convention a ceiling (#1479)
5abca4c 
The convention stated only a floor — non-obvious choices must carry a why —
so it could push comment volume up and never back. Add the missing half:
length calibration, and a destination test for a block that only reports
what the change did.

Written at block level on purpose. A per-clause form keyed on tense was
measured over 169 blocks from two model generations of this repo and had to
decide 17 of them, getting 4 wrong; it misfires on ~7% of load-bearing
blocks, systematically the longest ones. The doc carries that measurement,
the in-tree counter-examples, and why a duplicated figure needs a repo-side
grep rather than a review agent that never sees all the sites at once.

Mirrors claude-kit#36 (kit-canonical), which must land first.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UzC2UHsj9cRrQVzrRaHW8T
@tyabu12 @claude
📝 docs: teach the review gate the comment ceiling too (#1479)
d9bfc5f 
`### Code Quality` checked only that why-comments exist, so the sole review
gate on the unattended `/queue-consumer` path could push comment volume up
and never back.

The bullet is block-level and carries its own negative example. A shape-based
form was rejected: 78 in-tree comments match the provenance wording and most
state invariants a future editor must respect, so a wording trigger would
flag load-bearing text on the one path where no human sees the fix first.

Running the drafted bullet over six real blocks then moved two things. The
trigger is worded as an absence — "no sentence states a durable claim",
which an agent can substantiate by citing the sentence that saved the block
— rather than as "every sentence merely reports", which it cannot, and which
collapses on a one-sentence block. And precedence over the load-bearing-
remainder safeguard is now explicit, so a block that fires the trigger while
holding a live pointer no longer yields a finding whose only repair the same
bullet forbids. The gate also drops cross-file figure detection, which the
paired doc already assigned to a repo-side grep: a split review gives no
shard sight of every site, and the observed failure deletes the canonical
copy rather than the duplicate.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UzC2UHsj9cRrQVzrRaHW8T
@tyabu12 @claude
📝 docs: close the review's four citation gaps (#1479)
906ffd8 
- `~7%` had no reachable denominator: the adjacent "17 decided, 4 wrong"
  yields 2.4%, so a reader derives a different number and concludes one is
  stale. Name the population and say why it is the wider set.
- `PlaybackSpeed.swift:9` landed mid-sentence; the clause the claim rests on
  starts at :8.
- Restore `9pt` inside a quotation, in the section whose subject is quoting
  comments exactly.
- Record that `code-reviewer` ships arm 2 narrower than the form measured
  here, so the zero-false-positive figure is not read as covering the
  predicate that gate actually applies.

The two trials the section cites now have an auditable home — per site and
per verdict — in the ledger comment on #1479.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UzC2UHsj9cRrQVzrRaHW8T
@tyabu12 @claude
📝 docs: give length a writing-side procedure, and fix ~50% (#1479)
c7b1138 
The rule said length is the defect you will actually find, then offered only
the destination procedure — which deletes. Shortening is a different act, so
it needs its own: past ~6 lines, one rewrite at half the length, and the
rewrite wins unless it dropped a forward-looking fact. The threshold is the
measured 5.5 lines/block of the concise generation, not a round number.

19 -> 28 blocks per commit is +47%; ~50% was over-rounded.

Mirrors claude-kit#36.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UzC2UHsj9cRrQVzrRaHW8T
@tyabu12 @claude
📝 docs: withdraw the length threshold; scope the gate off doc comments (
3ca822a 
#1479)

/risk-review found the numeric authoring rule indefensible on four counts and
the gate inert on the two cases that motivated it.

The threshold is gone. `5.5` was not reproducible — the same three commits
give 3.42, 4.20 or 5.5 depending on where a block is judged to start, and the
definition was never published. `~6 lines` captured 22% of the tree's comment
blocks, 82% of them the `///` docs Hard Rule 3 requires, including a 49-line
`PasturaPrimaryButtonStyle` block whose every paragraph is forward-looking.
And "the rewrite wins" made deletion the default decision of the only party
able to notice the loss.

The finding behind it also shrank under re-measurement: +21% lines per block
over 23 vs 145 commits rather than +45%, the blocks-per-commit gap gone once
normalized by files touched, and `///` blocks showing no generation difference
at all. The ~45% survives only under a topic filter that cuts 259 of 453
blocks from one arm and 0 of 2,114 from the other — the same asymmetry that
refuted the C-class claim earlier in this branch, sign reversed. A per-commit
gate was calibrated and refuted; Fable 5 came in below both cohorts, so the
unit is the model, not the generation.

The gate now scopes to `//` blocks, which removes 716 descriptive `///`
one-liners from its reach and the collision with Hard Rule 3, and it asks for
a forward-looking rewrite instead of a cut — the repair its two motivating
cases actually need, both of which the previous wording left untouched.

The doc records the refuted gate, the per-model result, and that an
always-loaded line is itself untested here: three verbose drafts were written
under this very rule while it sat in context.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UzC2UHsj9cRrQVzrRaHW8T
@tyabu12 @claude
📝 docs: reconcile to kit's calibrated form — count before length (#1479)
0f9a719 
claude-kit#36 moved past the withdrawal in the previous commit, and its answer
is better than dropping the threshold: re-derive it from a percentile of the
concise baseline rather than a mean, which puts it at ~10 lines instead of ~6
and off the doc-comment population entirely.

Its calibration also reframes the finding. What separates the cohorts is count
rather than length — ~60% more blocks against ~35% longer ones over a shared
median block — so the rule now leads with the count, and a length-keyed
mechanism is aiming at the smaller half of its own defect. Three gate designs
were built and refuted at the commit and block level; the tool ships as cohort
measurement only. Fable 5 sits below both cohorts, so the axis is the model,
not recency.

Pastura keeps one local addition: the rewrite-wins default is exempted for
`///` blocks carrying measured values, which Hard Rule 3 mandates and which a
halving cannot preserve. That carve-out is this repo's, not kit's.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UzC2UHsj9cRrQVzrRaHW8T
@tyabu12 @claude
📝 docs: ブロック数は分母䟝存 — kit#37 の蚂正を取り蟌む (#1479)
70726f3 
kit から取り蟌んだ「count, not length」は撀回された。生の per-commit
カりントを、単䜍の倧きさが違うコホヌト同士で比べおいたため。

この doc は䞊の段萜で既に「blocks-per-commit はファむル数で正芏化するず
消える2.98 vs 3.03— コミットサむズだった」ず曞いおおり、盎埌の段萜が
その blocks-per-commit を芋出しに採甚しおいた。取り蟌み時に自分の反蚌の
䞊に乗せた圢で、内郚矛盟になっおいた。

固定範囲 1f8836e..9a40565 で枬り盎すず、分母を持぀2指暙が堅牢:
远加行に占めるコメント比 43.0% → 55.0%、行/ブロック 4.31 → 5.68 (+32%)。
ブロック数は分母で答えが倉わる — 100コヌド行あたり +31%、ファむルあたり
+10%、コミットあたり +63%。数え方でも倉わり、`//` ず `///` を分けるず
ファむルあたりは平坊䞊の段萜の 2.98 vs 3.03、kit のツヌルは合算する。

Fable 5 が刀定材料。自己正芏化された指暙では党郚最少なのに、生の
コミット単䜍でもファむル単䜍でも最倚になる1ファむル 39.8 行曞くため。

rule からは「count を先に芋ろ」の順序指瀺を萜ずしお䞡方を芋る圢に。
垞時ロヌドは 95,042 → 95,089 バむト+47、䞊限たで残り 411。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EXUZckBU1oD6hMoVCdy6iQ
@tyabu12 @claude
📝 docs: per-file の食い違いは原因を単離しおいない (#1479)
4e64d82 
前コミットで「ファむルあたりが平坊 (2.98 vs 3.03) なのは `//` ず `///` を
分けお数えたため」ず断定したが、暙本も違う — あちらは滑る窓の 23 vs 145
コミット、kit のツヌルは固定範囲の 26 vs 123 で䞡者を合算する。数え方単独で
平坊↔+10% を説明できるかは未怜蚌。

「確かめるのが高く぀くなら、原因は単離できおいないず曞け」を適甚しお
断定を倖した。行/ブロックにも同じ食い違いがある (+21% 察 +32%) ので䜵蚘した。

読み手は承認枈みの隙間には察凊できるが、誀った原因は匕き継ぐしかない。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EXUZckBU1oD6hMoVCdy6iQ
@tyabu12 @claude
📝 docs: kit#37 の残り4件を照合する (#1479)
1df9e16 
kit 偎が #37 の最終コミットで足した蚂正のうち、4件がミラヌに枡っお
いなかった。マヌゞ前に揃える。

- 比率が買うのはコホヌトの倧きさぞの免疫だけで、題材構成には無防備。
  この doc の C クラス撀回がたさにその圢なので、同じ節の䞭で
  「比率だから堅牢」ずだけ曞くず自分の反蚌ず噛み合わない
- Fable コホヌトは n=16。方向ずしお読む
- 3回の蚂正の共通圢は「分母」より広く「コホヌト間で揃っおいない共倉量」
- trailer を持たない適栌コミット72件がどのコホヌトにも入っおいない

垞時ロヌド局は䞍倉rule は倉曎なし、95,089 バむトのたた。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EXUZckBU1oD6hMoVCdy6iQ
@tyabu12
tyabu12 force-pushed the docs/comment-length-and-destination branch from 898f65c to 1df9e16 Compare August 14, 2026 15:53
@tyabu12
tyabu12 enabled auto-merge (squash) August 14, 2026 15:53
@tyabu12
tyabu12 merged commit cfe658f into main Aug 14, 2026
20 checks passed
@tyabu12
tyabu12 deleted the docs/comment-length-and-destination branch August 14, 2026 15:54
@tyabu12 tyabu12 mentioned this pull request Aug 15, 2026
Closed
tyabu12 added a commit that referenced this pull request Aug 15, 2026
@tyabu12 @claude
🧹 chore: 同䞀䞻匵の倚重蚘茉を1正兞+ポむンタに畳む
cb6cf30 
origin/main 差分の自己レビュヌで、同じ䞻匵が3〜4箇所に曞かれおいるのが
芋぀かった。#1480 が「重耇数倀はレビュヌ゚ヌゞェントではなく repo 偎
grep」ずゲヌトから倖した領域なので、code-reviewer は玠通りしおいる。

4系統をいずれも 3サむト → 2サむトに。残した2぀は圹割が違う
(Swift = 次の線集者が読む契玄 / eval-log = 実枬蚘録ずその導出)。
SKILL.md ずテストは玔粋なポむンタにした。

- nCtxTrain / b10327 の論拠: source doc を正兞に、テスト偎はポむンタ
- reason= 語圙が sweep の join key: source doc を正兞に、テスト偎は
  「なぜ pin するか」だけ
- speak_each の seeding 芏則: Swift case doc を正兞 (engine.md が自ら
  深郚を buildAndSeedDrySampler に委譲しおいる) に、SKILL.md はポむンタ。
  枬定倀 (10/26) は eval-log 1箇所のみ
- narrate の no-op emitter: eval-log 内で2回導出しおいたので1回に。
  成功時のオフセットず倱敗時の䞍可芖性は別の垰結なので䞡方残し、
  埌者は前者を参照する圢にした

あわせお #1480 の倩井 (~10行) を超えおいた2ブロックを曞き盎し、玔粋な
ナレヌション (emitDryUnavailable の「なぜ wrap したか」、seedTokens の
「なぜ抜出したか」) を萜ずした。guard 分割のコメントは「再統合するな」
ずいう制玄を明瀺する圢に曞き盎しおいる (元は分割理由の説明だけだった)。

本番 Swift の远加行に占めるコメント比 60.4% → 57.5%。倩井超えの2ブロック
は 20→15行 / 15→13行で、いずれも ~10行はただ超えおいる。半分にするず
前向きな事実 (throwing exit の非被芆、EngineLogger を䜿えない䟝存芏則) が
萜ちるため、#1480 の「曞き盎しが事実を萜ずしたなら元を採る」に埓った。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DZpHBzWfkHYaX8snJ8EBzq
@tyabu12 tyabu12 mentioned this pull request Aug 15, 2026
Merged
tyabu12 added a commit that referenced this pull request Aug 15, 2026
@tyabu12 @claude
♿ fix: muted 適甚監査 — batch 1 + 垞蚭ガヌド + §8 の合成地 (#1448) (#1486)
4091efd 
## Summary

`muted` の適甚監査#1448の **batch 1 + 垞蚭ガヌド + 芏範偎の曎新**。§8 の
sub-AA 免陀は「枬った地」にしか及ばない、ずいう #1427 の刀断をアプリ党䜓に適甚
する掃匕の第1匟。

- **台垳** `docs/design/muted-application-audit.md` — 98 サむトを file+symbol
で
  アンカヌし、5぀の misapplication クラスで裁定。䞡方向の察照぀き
- **batch 1** — must-read な 8 ラベルを `inkSecondary` ぞ repoint
- **垞蚭ガヌド** `MutedSweepLedgerTests` — `Color.muted` のファむル別出珟数を
  党䜓マップ比范で pin。**陀去だけでなく远加でも萜ちる**
- **合成地の arm** — 半透明りォッシュを `DesignTokensTests+MutedAsContent` が
  テスト時に実枬self-wash / moss / `rule`、+ 癜黒 bracket。台垳 §3.2 はその転蚘
- **芏範偎** — design-system §8 / §2.2、ADR-028 の新 Amendment、INDEX

batch 2–5 は未着手。§2.2 の適甚は #1485。

## 掃匕の過皋で出た2぀の発芋

**1. ADR-010 D8 の構造ガヌドは䞀床も䜕も怜査しおいなかった。** item 3 は
`StructuralBoundaryTests.resolveRepoRoot` の抜出を指瀺しおいたので、抜出前に
蚈枬した。シミュレヌタの test runner では `Bundle.main.bundlePath` の祖先に
`Pastura/Pastura` マヌカヌが存圚せずアプリはシミュレヌタのコンテナに入る、
`bundleWalkFound=NIL` → cwd フォヌルバックが `/`。走査察象4ディレクトリはすべお
䞍圚で、`fileExists` ガヌドにより `[]` が返り、**ファむルを1぀も読たずに「clean」
ず報告しおいた**。`SourceTreeProbe` は `#filePath` で解決する他のテストず同じ
手法。ガヌドには自前の non-vacuity floor を局ごずに眮いた。

真面目に動かした結果 `Models/Scenario.swift` が1件ヒットしたが、これは
`LocaleResolver` に蚀及する doc コメントで䟝存ではない。コメント陀倖を共有
プロヌブ偎に眮いた理由がこれで、そのファむルが䞡方向の察照の fixture になっおいる。

**2. 台垳 §3.2 のりォッシュ衚が3通りに間違っおいた。** arm を曞いお再珟しなかった。
数倀は**チャンネルを 0–255 に量子化する**スクリプト由来で`swiftui-traps.md` が
名指しする事故そのもの、節自身は「fixture ず同じ方法」ず称しおいた。
`ActiveModelChip` はカヌド地で枬られおいたが実際は
`.toolbarBackground(.hidden)` 䞋の `HomeView` ToolbarItem なので screen 地
dark 2.434 → 3.098。さらに2行は `muted` テキストが茉らない地だった。
珟圚は arm がテスト時に蚈算し、衚はその転蚘。**「新しい最悪ではなく未枬定の地」
ずいう結論自䜓は再蚈枬を生き延びた**。

## 蚈画からの逞脱3点

- **台垳 §1.1 を远加** — `HighlightShareCard` の `palette.muted`。母集団は
  `Color.muted` ずいう**綎り**で定矩されおいるので構造的に grep から挏れる。
  固定倖芳の `ImageRenderer` 曞き出しは生パレット盎読みが芁求されるため、
  これは lapse ではない。**S**曞き出し成果物に䜕を課せるかで刀定。詳现は䞋。
  第2の arm で抌さえた
- **ADR-028 の count mirror は再導出ではなく削陀**。蚈画は「最終コミットで
  再導出」だったが、`adr-writing.md` §4 は可倉圚庫を写すこず自䜓を犁じおおり、
  圓該節に数を持぀理由がなかった
- **§2.2 の blast radius は 9 ファむル / 5 画面**design-system の「8画面」は誀り

## Test plan

- `scripts/xcodebuild.sh test -skip-testing:PasturaUITests` — **3462
tests / 286 suites green**
- `swiftlint lint --quiet --strict` — clean
- `scripts/xcodebuild.sh build -destination 'generic/platform=iOS'
CODE_SIGNING_ALLOWED=NO`
— device-only 領域`SettingsView+Models` は䞞ごず `#if
!targetEnvironment(simulator)`の
  コンパむル確認 **BUILD SUCCEEDED**
- **ガヌドが実際に発火するこずを mutation で確認**成功パスは䜕も蚌明しないため:
  1件の耇補ず1件の陀去を入れ、`perFileMutedCensusMatchesTheLedger` が
  `expected 1 → found 2` / `expected 1 → found absent` を列挙しお萜ちるこず、
  `rawPaletteReadsStayWithinTheRecordedSet` も萜ちるこずを確認しお revert
- 合成比は Swift 偎ず独立実装の2系統で、党倀が小数点3桁たで䞀臎

### /risk-review3クラスタ・䞊列

芏範そのものが審査察象なので、`code-reviewer` の埌に `/risk-review` を実斜。
**芏玄ゲヌトが通した埌で 8 Warning** が出た。䞻なもの:

- **地をたた palette スロットから読んでいた。** §1.1 は共有カヌドの地を
  `screenBackground`3.329 / 3.779ず曞いおいたが、カヌドは背景の䞊に
  moss の light leakradialを重ねおおり、モデル名の行はその䞭に入る。
  最倧 leak での bound は **2.932 / 3.140**。これは本 PR が
  `ActiveModelChip` に぀いお蚘録したのず**同じ誀り**を2節あずで繰り返したもので、
  蚂正より教蚓のほうが重い — 地はビュヌ階局の性質で、パレットをいくら読んでも出おこない
- **§8 が砎壊方向に読めた。** 「りォッシュ䞊では §8 を匕甚できない」ず眮換先だけがあり、
  「**未枬定は違反ではない**」の䞀文が無かった。コントラスト掃匕をする読者が、
  意図的に quiet なラベルを機械的に䞊げる経路が実圚した
- **B4 のゲヌトが到着時点で満たされおいた。** 「§8 が composited ground の routing を
  蚀うたで」は §8 の `*-on-wash` バレットが既に答えおいるので、ゲヌトずしお機胜しない
- **ADR-010 DoD-10 が砎れたたた**だった。literal に zero-match grep を芁求しおおり、
  本 PR がガヌドの述語を倉えた偎だけ盎しお ADR を攟眮しおいた
- §5 の2行を再裁定1぀は §2 が退けた「他に曞いおいない」基準で裁定されおいた、
  B2 の8行を実 Swift シンボルぞ、B2 に実機 QA 芁求を远加

bracket 論蚌の前提䞍透明地は **OK** 刀定。アルファ合成は手前で確定 RGB に
なっおいれば地の生成機構を問わないため、material 由来の地にも及ぶ。

### Review

`code-reviewer`Opusを **2 shard に分割**14 ファむルは
`subagent-usage.md` §2 の hard split 超過。3 iteration 回しお 1 Critical +
10 Warning + 6 Suggestion をすべお凊理。**iteration 2 / 3 の指摘はすべお
「前の fix コミットが曞いた文」の䞭にあった** — レビュヌ修正自䜓が䞻匵を含む
線集で、既定では誰も再怜査しない、ずいう圢。うち1件は撀回した䞻匵の双子を
57行䞋に残しおいた sweep miss。

芏範そのものを審査察象に含むため、`code-reviewer` に加えお **`/risk-review` を
掚奚**先䟋 #1466 / #1480。芏玄ゲヌトは「審査察象が芏玄自身」だず原理的に
芋られない。

## コメント/ドキュメント監査远加コミット6本

この PR 自身の diff を #1480 の「Why comments 倩井」に照らしお監査した。in-session の
レビュヌず Fable のセカンドオピニオンが独立に走り、その埌 Opus critic が **Critical 3件**を
出しお圓初案を3か所で芆しおいる。

**誀りが3件**重耇ずは別:

- `SettingsView+Models` / `SettingsView+PastResults` /
`design-system.md:802` が WCAG 1.4.3 の
  非掻性陀倖を **§8 に垰属**させおいた。§8 は disabled に䞀切蚀及しおおらず、陀倖を蚘録しお
  いるのは §2.9、トヌクンは §2.7 — 本 PR の台垳 §6.1 が既にそう曞いおいた。最初は1サむトしか
  盎しおおらず、critic が class の列挙を芁求しお残り2件が出た`1.4.3` のリテラルではなく
  §8 ぞの垰属を列挙する必芁があった
- `ModelSettingsRow` の「the two below it」が switch の䞊びず逆で、実際に䞋にあるのは同じ
  コメントが候補倖ず曞いおいる moss アヌム
- 台垳 §7 の `| **B5** |` 行が段萜の埌に孀立しおいお GFM で描画されない

**重耇を4クラス解消**。正本の決め方は既存の芏範に埓った — ADR-028 § "Where new amendment
content goes"measurement ず撀回した草皿は amendment、`adr-writing.md` §4圚庫の数は
写さない / INDEX は routing。単調性論蚌だけは圓初案ず**逆向き**に寄せおいる: 玔癜/玔黒の
ブラケット2゚ントリが存圚しおよい唯䞀の根拠なので、fixture の doc に残さないずテスト偎から
根拠が消える。

**PR body ぞ移した蚘述**コメント/ドキュメントからは萜ずした:

- design-system §2.2 が持っおいた「この節が以前持っおいた『8画面』はファむル数を画面数ずしお
  曞いたもので、#1448 の掃匕では数だけ盎しお単䜍の誀りをそのたた䌝播させかけた」。前向きな
  指瀺ファむル数ず画面数を取り違えないこずは §2.2 に残っおいる
- ADR-010 D8 が持っおいた「旧 revision は `rg 'LocaleResolver'
Pastura/Pastura/{Engine,LLM,Models,Data}`
  がれロ件を返すこずを芁求しおいたが、`Models/Scenario.swift` の doc コメントがそれを砎る䞀方
  D8 自䜓は満たされおいる。CLAUDE.md § "Decision Records" に埓っお in-place 修正した — 決定は
  䞍倉で、リテラルな受け入れコマンドのほうが出荷コヌドに぀いお誀りになっおいた」

**follow-up**: #1488 — 枬定倀が `docs/**` の耇数面に手写しされる件。#1479 が「重耇数倀は
レビュヌ゚ヌゞェントではなく repo 偎 grep」ず既に振り分けおおり、その docs 版。#1477 ずは
母集団が違うのでスコヌプを広げず別 issue にした。

**レビュヌ分割**: ブランチは `subagent-usage.md` §2 の soft budget を超えおいる。シャヌド境界は
`docs/decisions/**` ず `docs/design/** + Swift +
tests`。**跚ぐ䞻匵重耇が実際に䞀本化できたかは
どちらのシャヌドからも芋えない**ので、メむンセッションで重耇 grep を再実行しお担保した。

## Device QA

ADR-028 gate 4/5。**䞡倖芳light / darkで実機**、シミュレヌタでは䞍可。

1. **蚭定 → モデル管理**`#if !targetEnvironment(simulator)` でシミュレヌタには
存圚しない: `ModelSettingsRow` の `Loading
` / `Not supported on this
device`、
   `OrphanedModelFileRow` のファむル名、モデル切替がブロックされおいる時の理由文が
`inkSecondary` で読めるこず。同じ switch 内の `Ready` / `Downloading %d%%`moss 系ず
   `Error:`danger 系は**意図的に色が違う**ので揃えないこず
2. **蚭定 → 芳察履歎**: `Storage used: %@` ず clear がブロックされおいる時の理由文
3. **モデル DL 完了オヌバヌレむ** `DLCompleteOverlay` の `Tap anywhere to begin` —
   `.ultraThinMaterial` 䞊なので**静的な比が存圚しない**。方向でのみ論蚌しおいる
   `inkSecondary` は `muted` より暗く、`nightInkSecondary` は `nightMuted` より
   明るいので、実機で実際に読めるかの確認がここだけ効く
4. **さがす → シナリオ詳现**の掚奚モデル欄、切替ブロック理由文

## Related

- Part of #1448batch 1 / 5。batch 2–5 は未着手なので close しない
- #1485 — §2.2 セクションヘッダヌの適甚batch 5
- ADR-028 § Amendment 2026-08-15

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
@tyabu12 tyabu12 mentioned this pull request Aug 19, 2026
Merged
tyabu12 added a commit that referenced this pull request Aug 19, 2026
@tyabu12 @claude
✹ feat: /simplify-doc — diff-scoped なコメント/ドキュメント剪定スキル (#1502)
c3d0765 
## Summary

PR の終盀で毎回手曞きしおいた「origin/main ずの差分から、自明・冗長・重耇したコメント /
ドキュメント蚘茉を削陀・圧瞮する」パスを `/simplify-doc` スキルずしお固定する。

生成偎`context-budget.md` / `knowledge-layering.md`
の蚘茉匷化で抑える方針は効かなかった。`knowledge-layering.md` § "Anti-pattern: a comment
written for the reviewer"
が曞いおいるずおり、コメント量は「最近の指瀺」ではなくモデル特性に远随するため。よっお「生成させおから刈る」を正芏工皋ずしお受け入れ、**刈る偎の手順ず怜蚌**を固定する。

アドホックなプロンプトに察する付加䟡倀は **Step 3 の怜査矀**過去の圧瞮 PR で実際に螏んだ倱敗モヌド:

- **A. 埌方参照** — 削陀**リネヌム**の前に、**空癜を含たないトヌクン**で匕甚元を grep
する。行折り返しが構造的に起きえないため。最も皀なトヌクンを遞び結果を列挙し、**列挙できない䞊䜍集合に察しおは削陀しないそれ自䜓が Keep
刀定**。れロ結果は生息域に眮いた陜性察照が発火しおから信甚する
- **B. 「重耇だから削る」は䞻匵** — 移蚭先を grep で実圚確認。未蚌明なら Keep
- **C. ミラヌ** — kit ミラヌの共通栞は察象倖䞀方向 reconcile が壊れる、rule↔paired
doc、CLAUDE.md↔README/CONTRIBUTING
- **D. ファむルが自分に぀いお述べる数** — 最終コミットで再蚈枬
- **E. 機械可読な散文** — ADR roster の1行段萜、ADR-006 行の3
conjunct、`.claude/rules/*.md` の `paths:`。いずれも fail-open なので壊しおも沈黙になる

`CLAUDE.md` の `/orchestrate` ゚ントリポむント芏則に carve-out を远加し、`gh pr create` の
trim nudge から `/simplify-doc` を名指しする。

### 自動発火に぀いお確定

公匏ドキュメントで確認枈み: *"Command hooks communicate through stdout, stderr, and
exit codes only. They can't trigger `/` commands or tool
calls."*[hooks-guide](https://code.claude.com/docs/en/hooks-guide.md)。党むベントにスキル起動の口はなく、フック以倖の
event-triggered 起動機構も存圚しない。**テキスト泚入が䞊限**。`permissionDecision: deny`
はより匷い結合ずしお利甚可胜だが、サむズ閟倀は「䜕かを削る必芁がある」蚌拠ではないので意図的に採らない — スクリプトヘッダに蚘録した。

## Test plan

- `scripts/tests/check-claude-md-modified-test.sh` — 新芏 case (s) を含め党ケヌス
green
- シェルゲヌト党 22 スむヌト green`scripts/*.sh`
を觊ったため、`.claude/rules/ci-workflows.md` の芁求どおり
- **摂動テスト2回**緑は蚌拠にならないので、壊したら赀くなるこずを確認:
- `TRIM_MSG` 冒頭文を厩す → case (l) ず (q) が赀 → 埩元しお green。`+N always-loaded /
+N path-scoped` が tier 分類の陜性察照であるこずを実蚌。远蚘のみに制玄し、その理由を `TRIM_MSG` 盎䞊に固定
- `/simplify-doc` の远蚘末尟を削陀 → **case (s) のみ**が赀 → 埩元しお green。既存の `$TRIM`
マヌカヌでは刀別できない領域を case (s) が実際に瞛っおいるこずを実蚌
- iOS ビルドは pre-commit hook 経由`scripts/**` が build-relevant

## Review

`code-reviewer`Opus2å‘š +
`/risk-review`3クラスタ䞊列。芏玄ゲヌトは審査察象が芏玄自身だず原理的に芋られない#1480 /
#1498ため、䞡方を回した。

- 1å‘šç›®: Critical 1 + Warning 13。**Critical は check A の根拠が2぀の別事䟋を混同しおいた**
— `tr '\n' ' '` の正芏化は `claim-verification.md` の折り返し匕甚を拟える拟えないのは継続行に `>
` が付く圢。党指摘を実枬で裏取りしおから反映
- 2呚目差分ずファむルのみを枡したフレッシュな reviewer、前呚の自䜜散文は䞍可芖: Critical 0 + Warning 4
で、**4件ずも1呚目の修正が新たに入れた欠陥**「実匕甚2件」が実は4件 / CLAUDE.md が「2぀のガヌド」ず曞いお3぀挙げる /
`Step 0.5` ぞの参照がどこも指しおいない / base-ref を怜蚌しお䜿っおいない
- レビュヌは䞊限2呚で打ち切り。芋送った提案1件case (s) を case (q) に畳むは理由をコミットに蚘録

2クラスタで carve-out の刀定が OK / Warning
に割れた。䞡者ずも「実際に効いおいるのは構造的事実」で䞀臎しおいたため、䞊䜍偎構造的根拠を䞻、撀回可胜なガヌドを埓に寄せた。

## Device QA

実機QA䞍芁 — スキル定矩・゚ヌゞェント指瀺・シェルフックのみで、アプリのコヌドパスに觊れない。

Context-economy: CLAUDE.md に always-loaded +8行carve-out のみ、trim nudge
閟倀10未満なので自己発火せず。スキル本䜓 299 行は `.claude/skills/**` で always-loaded 集蚈の察象倖
— フックの numstat pathspec にも footprint sum にも含たれない。レビュヌ指摘で削ったもの:
自己蚀及で腐る数倀2件、`TRIM_MSG` 远蚘の列挙的内蚳`context-budget.md` の Drop 分類に該圓、Step 2
の重耇した再掲の蚀い蚳。

Closes #1501

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@tyabu12 tyabu12

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

1 participant

@tyabu12