Skip to content

refactor(skills): split the FSL reference so activation loads 7,102 tokens instead of 19,821 - #942

Merged
rizumita merged 1 commit into
mainfrom
perf/941-skill-references-split
Aug 28, 2026
Merged

refactor(skills): split the FSL reference so activation loads 7,102 tokens instead of 19,821#942
rizumita merged 1 commit into
mainfrom
perf/941-skill-references-split

Conversation

@rizumita

Copy link
Copy Markdown
Collaborator

Problem

Closes #941. Closes #763.

skills/fsl/SKILL.md は skill が発火するたび全文がコンテキストへ載る。#941 がその量を実測し、
19,821 トークン(reference.md は読まれると 49,300)であることを示した。
SKILL.md は「spec を書く前に必ず reference.md を読め」と指示しており、その指示は
#763 が示すとおり authoring skill 6件すべてに複製されていた。

2つは同じ PR で動かす必要がある。 指示の重複だけ直しても reference.md は巨大な塊のままで、
分割だけしても6 skill が「全部読め」と言い続ければ効果が出ない。

Contract change

分野別 references/ への分割

skills/fsl/reference.md(2,128行)を削除し、skills/fsl/references/ の9ファイルへ分割:

ファイル 実測トークン
syntax.md 20,306
commands.md 19,208
layers.md 8,355
impl.md 5,978
errors.md 3,370
when-to-use.md 1,993
advanced.md 1,481
nl-to-syntax.md 1,051
practices.md 713

SKILL.md は 789行 → 339行、8節(役割振り分け / 実行方法 / 形式化メモ / 標準ワークフロー /
最小テンプレート / 構造的落とし穴 / 役割別入口 / Reference index)。索引は
references/*.md が何を答えるファイルかを示す。

6 authoring skill の無条件読込を解消(#763)

fsl-business / fsl-design / fsl-requirements / fsl-from-code /
fsl-requirements-document / fsl-design-review の「reference.md を必ず読め」を、
core の索引から必要な topical reference だけを読む指示に変えた。
言い換え版(fsl-from-code の短縮版、fsl-requirements-documentfsl-design-review
言い換え)も含めて6件すべて。

結合面(分割の副作用でゲートを弱めないため)

変更
rust/fslc/tests/literate_docs_contract.rs skills/fsl/reference.md への anchor を移動先へ。anchor のテキストは変えていない
rust/fslc/tests/causal_docs_contract.rs 同上(causal の review-only 規則)
rust/fslc/tests/mutation_docs_contract.rs 同上
tools/aggregate_changelog.sh is_product_surface_pathskills/fsl/references/* を追加
README.md / skills/README.md / skills/fsl-delivery/SKILL.md / Claude rules・skills 参照パス更新

aggregate_changelog.sh の更新が特に重要である。is_product_surface_path
skills/fsl/reference.md を製品面として名指ししていたので、更新しなければ
分割後は skill reference を変えても changelog fragment が要求されなくなる

Test evidence

効果(同一 baseline で新旧を比較)

--exclude-dynamic-system-prompt-sections を付けた #941 の手順で、同じ baseline (45,814) に対して
mainSKILL.md と本 PR の SKILL.md を測った
:

トークン
mainSKILL.md 19,821
本 PR の SKILL.md 7,102
削減 12,719(-64%)

main 側の 19,821 は #941 の報告値と完全一致する。

計測手順についての実測(#941 の記述を1点訂正)

#941--exclude-dynamic-system-prompt-sections を付ければ「決定的に再現する(k=3 で完全一致)」
と書いている。同一セッション内では確かに決定的で、baseline を5回・with を4回測って
すべて同値だった(46,567 / 53,669)。

しかしセッションをまたぐと baseline が変わる(45,814 / 46,066 / 46,567 / 47,745 / 47,769 を
観測)。したがって別々のセッションで測った前後の数字を引き算してはいけない
本 PR の数字は上記のとおり同一 baseline に対する新旧比較で取っている。

途中で見つけた欠陥: 移動ではなくコピーになっていた

最初の実装では First, decide whether FSL fitsRecommended practices
SKILL.mdreferences/ の両方に同一内容で存在していた。オーケストレーターが計測して
9,782(-51%)で目標未達と分かり、本文を照合して重複を特定した。
除去して現在の値になった。計測しなければ「-51% 達成」として通っていた。

検証(すべて exit 0)

  • python3 tools/check-design-citation-headings.py check — citations=74, findings=0
  • bash ./tools/aggregate_changelog.sh check
  • cargo test -p fslc-rust --test literate_docs_contract --locked — 6 passed
  • cargo test -p fslc-rust --test causal_docs_contract --locked — 2 passed
  • cargo test -p fslc-rust --test mutation_docs_contract --locked — 3 passed
  • cargo clippy --workspace --all-targets --locked -- -D warnings
  • git diff --check

ローカルリンクの解決をオーケストレーターが全件確認した: SKILL.md
references/*.md27本すべてが解決、壊れゼロ

移動以外の変更(最小限、全件列挙)

内容は節単位で移動し、変更は移動後に意味が切れないための補正のみ:

  • core の無条件 reference.md 読込 → 索引ルーティング
  • 標準ワークフロー手順4を commands.md へ移す際、独立して読めるよう
    「Extended workflow commands」の導入文を追加
  • above / below / reference.md §N を、移動先への相対リンクまたは明示名に修正
  • 6 authoring skill の指示文
  • reference.md は削除し、索引を SKILL.md に一本化した(2箇所に索引を持たない)

未計測の懸念(#941 が挙げているもの)

分割前は「reference.md を読む/読まない」の二択なので、読まなければ 0 で済んだ。
分割後は「複数ファイルのうち必要なものを読む」になるため、エージェントが必要以上に読めば
総量が増え得る
。この筋は未計測である。ファイル単体のサイズ比較では判断できないので、
実タスクでの総トークンで確認する必要がある。

Linked issue

Closes #941, closes #763

@rizumita

Copy link
Copy Markdown
Collaborator Author

Authorship note: this branch was produced under my orchestration and is being admin-merged without an independent human review, so it is an authored change rather than a reviewed one. Its evidence is the same-baseline token measurement (main 19,821 → PR 7,102, -64%), 27/27 local links resolving, and tools/aggregate_changelog.sh:543 extended to skills/fsl/references/* so the split does not silently drop the fragment requirement.

@rizumita
rizumita merged commit 927728f into main Aug 28, 2026
21 checks passed
@rizumita
rizumita deleted the perf/941-skill-references-split branch August 28, 2026 05:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant