standards-refactor

Files (1)

• SKILL.md

SKILL.md (first lines)

# standards-refactor

指定範囲の既存コードを、振る舞いをテストで固定してから書き直し、PR にする。実行者は既定で Codex。Claude が実行してもよい。

このスキルはポリシーの中身を持たない。判断の正本である standards の `CODING.md` を実行時に取得して読む。以下を1コマンドずつ実行し、exit code と本文を確認する。

```bash
git -C ~/projects/elchika-inc/standards fetch --quiet origin
git -C ~/projects/elchika-inc/standards show origin/main:software/CODING.md
```

ローカル checkout が無ければ `gh repo clone elchika-inc/standards <一時ディレクトリ>` で取得したコピーの `software/CODING.md` を使う。ローカル checkout の作業ツリーのファイルを直接読まない（古い版の可能性がある）。取得に失敗したらエラーを報告し、ポリシーを読めるまで進めない。

## 進め方

段0〜5を順に実行する。対象範囲、各段の検証結果、段2のコミット SHA、直さなかった箇所、未修正のバグを PR 本文の下書きに記録する。中断後はその記録と実際の履歴・差分を照合して再開し、確認できない段を完了扱いにしない。

### 段0: 前提を確かめる

**やること**:

- 隔離した worktree で作業する。既に対象用の隔離済み worktree があるならそこで続ける。
- 対象範囲（ファイル・ディレクトリ・関数）を受け取る。未指定なら、長い関数・深いネストの候補を挙げて止まり、選んでもらう。
- 対象プロジェクトの `AGENTS.md` を読み、Key Commands の test と check を実行して出力・exit code を記録する。N/A は Key Commands に理由が明記されているものだけとして記録する。コマンドが不明なら推測せず確認する。
- テストファイルの実際の置き場所を確認する。段4の4パターンに当たらないテストがあれば、その場所を含むパターンを足して記録する。
- 書き直す前の関数の長さとネストの深さを実測し、数え方も記録する。段4で同じ数え方を使うための比較値であり、合否の数値閾値は設けない。

書き直す前から test か check が失敗していたら止めて報告する（元からの失敗か、今回の失敗かを切り分けられなくなるため）。

**終わった判定**: 対象が決まり、ベースラインの test と check が exit 0。明記された N/A は理由を記録できている。

### 段1: 読みにくい箇所を見つける

**やること**: `CODING.md` の節ごとに対象を読み、「原則・場所・読み手がどこで止まるか」を一覧にする。直さないと決めた箇所も理由つきで残す。対象範囲の外へ変更を広げない。

**終わった判定**: 書き直す箇所と直さない箇所の一覧ができている。

### 段2: 振る舞いを固定してコミットする

**やること**:

1. 対象の公開面と現在の入出力を確認する。既存テストが `CODING.md` §5.2 の関わる類型をどこまで押さえているか、テストと類型の対応表を作る。足りない類型のテストを足し、関わるのに外す類型は理由を記録する。
2. 実装の写しになっている既存テストは、書き直しより前（段2）に振る舞いのテストへ置き換える。
3. 足したテストは、一度対象を壊して失敗するのを確かめてから戻す。
4. 意図的に壊した実装を元に戻し、現状のコードで test が成功することを確認する。バグも含めた現在の振る舞いを固定し、期待値を望ましい仕様へ変えない。
5. **実装を書き直す前に、ここまでを1コミットにする。** その SHA を「段2のコミット」として記録する。意図的な破壊や書き直しをこのコミットに含めない。

**終わった判定**: 追加・置換したテストが現在の実装では成功し、意図的に壊すと失敗した。写しテストの置換と類型表ができ、段2の独立したコミットが存在する。テスト追加と書き直しを同じコミットにまとめた状態では段3へ進めない。

### 段3: 原則ごとに小さく書き直す

**やること**: 段1の一覧に沿って原則ごとに小さく書き直し、毎回 test を成功させてコミットする。

段2のコミットより後は、テストファイルを変更しない。

公開面（export されている名前、関数の引数と戻り値、API の応答の形）を変えない。薄い層でも export されていれば残し、PR 本文の『直さなかった箇所』に理由とともに書く。

既存の try/catch などを除去する前に、そこへ到達する入力と現在の振る舞いを確かめる。除去すると振る舞いが変わるものは残し、段2のテストで固定した入力と残した理由を「直さなかった箇所」に記録する。ポリシーへの適合を理由に現在の振る舞いを変えない。

test が失敗したら実装側を見直す。同じ原則について、書き直しで test を緑に戻せない状態が3回続いたら止めて報告する。

**終わった判定**: 書き直しの全コミットで test が exit 0。公開面と段2のテストを保っている。

### 段4: 振る舞いと差分を確かめる

**やること**:

1. Key Commands の test と check を再実行し、出力・exit code を記録する。
2. 未コミットの変更を残さず、段2から HEAD までのテストファイルの差分を確認する。次の `<段2のコミット>` は、記録した実際の SHA に置き換えて実行する。

```bash
git diff --exit-code --stat <段2のコミット>..HEAD -- '*.test.*' '*.spec.*' 'tests/' '__tests__/'
```

期待は exit 0 で出力が空。exit 1 なら段3の「テストファイルを変更しない」に反しているので止まる。その他のエラーも検査未完了として止めて報告する。段0で追加したテストのパターンがあれば、このコマンドにも足し、PR 本文にそう書く。

段2のコミットより後に `main` をマージで作業ブランチへ取り込んだとき（並行で作った別の PR が先にマージされ、`gh pr update-branch` などで追いついたとき）は、上の検査を使わない。`<段2のコミット>..HEAD` には取り込んだ `main` の変更が入り、別の PR が変えたテストで exit 1 になるため。代わりに、次の 2 つの出力がバイト単位で一致することを確かめる。三点ドットは分岐点からの差分なので、取り込んだ `main` の変更は出ない。パターンは上の検査と同じものを使う。リベースで追いついたときは段2のコミットの SHA が変わるので、記録した SHA を新しいものに直したうえで上の検査をそのまま使う。

```bash
git fetch origin
git diff origin/main...HEAD -- '*.test.*' '*.spec.*' 'tests/' '__tests__/' > "${TMPDIR:-/tmp}/freeze-<段2のコミット>-after.diff"
git diff <段2のコミット>^ <段2のコミット> -- '*.test.*' '*.spec.*' 'tests/' '__tests__/' > "${TMPDIR:-/tmp}/freeze-<段2のコミット>-stage2.diff"
test -s "${TMPDIR:-/tmp}/freeze-<段2のコミット>-stage2.diff"
cmp "${TMPDIR:-/tmp}/freeze-<段2のコミット>-after.diff" "${TMPDIR:-/tmp}/freeze-<段2のコミット>-stage2.diff"
```

期待は 5 つとも exit 0。差分は作業ツリーの外へ書き（未追跡のファイルを作業ツリーに残さないため）、ファイル名に段2のコミットの SHA を入れる（並行で確かめる別の PR と同じ名前で上書きし合わないため）。`git diff` が失敗すると出力は空になり、空どうしは一致して見えるので、`cmp` だけでなく `git diff` の exit code と、段2の差分が空でないこと（`test -s`）も確かめる。取り込んだ `main` も同じテストのファイルを変えていた場合（ぶつからずに取り込めた場合を含む）は、差分の行番号などがずれて一致しないことがある。一致しないときは止めて報告する。

3. 関数の長さとネストの深さを、段0と同じ数え方で実測して前後を並べる。

**終わった判定**: test と check が exit 0（段0で確認した N/A は理由を再掲）、テスト差分なし、前後の実測あり、の3点を確認できている。

### 段5: PR にする

**やること**: 1 PR = 1 対象範囲として、下書きから次の6節を持つ本文を作る。見出しはそのまま使い、該当がない節は「なし」と書く。

| PR 本文の見出し | 書くもの |
|---|---|
| `## 原則ごとの変更` | `CODING.md` の節、対象箇所、読みやすさの変化、対応するコミット |
| `## テストした条件` | 段2で足したテストと既存テストが押さえる類型を `CODING.md` §5.2 の類型名で記す。段2のコミット SHA と、意図的な破壊で失敗し復元後に成功した結果も記す |
| `## 外した条件と理由` | 対象の振る舞いに関わるのにテストしなかった類型とその理由。無ければ「なし」。振る舞いを変えない PR でも、このスキルでは段2の固定範囲を報告する |
| `## 直さなかった箇所` | 段1で見つけたが直さなかった箇所と理由。公開面のため残した薄い層や、振る舞い維持に必要な try/catch も含む |
| `## 見つけたバグ（直していない）` | 発見したバグの入力・現在の振る舞い・仕様との差。今回直していないこと |
| `## 前後の実測` | 関数の長さ・ネストの深さの前後と数え方、test / check のコマンド・出力・exit code、テスト差分の確認結果と追加したパターン |

PR を作成し、対象プロジェクトの通常のレビューサイクルに乗せる。レビュー修正にも段3のテスト凍結と公開面維持を適用する。

**終わった判定**: 対象範囲の PR が開いている。URL と検証結果、直さなかった箇所を報告する。マージはプロジェクトの方針に従う。

## 止まって報告する条件

- 公開面を変えないと直せない。
- 書き直しに合わせてテストを直す必要が出た（振る舞いが変わった証拠）。
- I/O を差し替える足場が無く、テストで振る舞いを固定できない。
- 指示と実態が矛盾する。

停止時は、対象・段・実行コマンドとエラー・最後に確認できたコミットを報告する。ユーザーの停止・範囲変更の指示が来たら影響する作業を止め、再開点を記録する。

**バグを見つけたときは直さずに PR 本文へ記録し、作業を続ける。** 段0のベースライン失敗と、段3の同じ原則で3回失敗した上限は、それぞれの停止条件に従う。

From elchika-inc/agent-toolkit, MIT.

More from elchika-inc/agent-toolkit