繰り返す作業を型にする — skillの設計資料を4ファイルで持つ

資料が整っても、毎週同じ手順を口頭で指示していれば、指示の内容は毎回ぶれる。この章では、繰り返す作業を型にして呼び出すだけの状態へ移す。あわせて、手順書とは別に「なぜその手順にしたか」を持つファイルを作る。「資料の書き方をそろえる — AIが1ファイルで迷わない冒頭と目次を決める」で本文から追い出した経緯の行き先が、ここで決まる。

目次

---

1. 何が起きるのか

毎週やる作業がある。投稿の下書きを作る、記事の構成を組む、素材を整理する。どれもAIに任せられるが、任せ方が口頭のままだと問題が出る。

指示が毎回ぶれる。 先週は「マイルールを参照して」と書いたが、今週は書き忘れる。出てくるものの質が週によって変わり、原因が指示なのかAIの調子なのか分からない。

指示が長くなり続ける。 一度うまくいかなかった点を補うために、次から一文足す。それを繰り返すと、指示が20行を超える。毎回それを貼るのが面倒になり、省略し始める。省略した部分から、また品質が落ちる。

改善が積み上がらない。 「今回はこう直した」がその会話の中だけで消える。次の週には忘れていて、同じ指摘をもう一度することになる。

なぜその手順なのかが失われる。 手順を改善していくと、一見無駄に見える工程が残る。「先に確認を挟む」「ここでいったん止める」といった工程には理由があるが、書いていないと後から自分で消してしまう。そして消した理由で困り、また戻す。

2. どう決めたか

繰り返す作業は、手順書として1ファイルに固定する。ツールによって呼び方は違うが、Claude Codeではこれをskillと呼び、/コマンド名 で呼び出せる。

そのうえで、設計資料を4ファイルに分けて持つ。手順書とは別の場所に置く。

置き場所は、手順書とは別のフォルダーにする。

skills設計/<コマンド名>/
├── 設計書.md      (今の仕様)
├── 設計判断.md    (なぜその仕様にしたか)
├── 今後の課題.md  (既知の制約・未解決事項)
└── 変更履歴.md    (時系列の「問題→対応」ログ)

手順書とは別の場所に置く理由:手順書は実行時にAIが読むファイルになる。ここに設計意図が混ざると、実行のたびに関係ない文章を読ませることになる。手順書は手順に徹させる。

各ファイルの書き方

設計書.md には今の仕様だけを書く。「なぜそうしたか」「まだできていないこと」「以前はこうだった」は書かない。判断理由を1〜2語添える程度は許容するが、節を立てて理由を論じ始めたら設計判断.md へ移す。

設計判断.md は見出しを「なぜ〜したか」の形にし、1判断1節で書く。検討したが採用しなかった案に触れてよいが、「以前はこうだったが指摘を受けて変えた」という変遷は書かない。

今後の課題.md は、課題が解決したらその項目を削除する。何をどう解決したかは変更履歴側に残る。「今はこうしている」で終わらせず、何が未解決かが分かるように書く。

変更履歴.md は表形式(日付・問題/きっかけ・対応)にする。削除・上書きはせず、下に追記していく。「問題・きっかけ」には、何が起きたか・どんな指摘を受けたかを具体的に書く。

更新の順番を固定する

仕様を変えるときは、この順で行う。

1. 何が問題だったか・どんな指摘を受けたかを、変更履歴.md に追記する
2. 実際に手順書を変更する
3. 変更の性質に応じて、設計書・設計判断・今後の課題を更新する
4. 索引の一覧に、まだ載っていなければ追記する

1を先にする。 直してしまうと、何が問題だったかを忘れる。直る前の状態を覚えているうちに書く。

3. なぜ手順書と判断理由を分けるのか

同じファイルに書いた方が、探す手間は減るように見える。分けているのは、読む場面が違うためになる。

手順書を開くのは、実行するときになる。このときに欲しいのは「次に何をするか」だけで、なぜその順番なのかは要らない。理由が混ざっていると、手順を追う目が毎回それを飛ばすことになる。

設計判断を開くのは、手順を変えようとするときになる。「この工程、要らないのでは」と思ったときに開く。ここで理由が書いてあれば、消してよいかが判断できる。

この2つは、同じ日に開かない。片方を開いているとき、もう片方は邪魔になる。

②の「経緯は消すが根拠は残す」が、ここで置き場所を得ている。 資料本文からは経緯を追い出したが、経緯そのものが要らないわけではない。変更履歴.md は「経緯を読むために開くファイル」なので、日付と旧仕様を書いてよい。設計判断.md は根拠を現在形で持つ。この2つを分けているから、資料本文をきれいに保てる。

変更履歴には、思わぬ使い道がある。 「どんな問題があって、どう直したか」の記録は、そのまま発信の素材になる。うまくいった完成形より、詰まった過程の方が読まれる。記録を残す手間は、書くときに回収できる。

4. なぜ動作フローだけ二重に持つのか

2章の表を見ると、動作フローだけが手順書と設計書の両方に入っている。他の項目は必ずどちらか一方なのに、ここだけ例外にしている。

意図的にそうしている。

手順書の側から見ると、全体像が無いのは致命的になる。AIは手順書を上から読んで実行するが、途中に「ユーザーに確認する」工程があると、そこで止まらなければならない。全体像が冒頭に無いと、止まる場所を知るには全章を読むしかない。

設計書の側から見ると、全体像が無いと工程を確認するために手順書を開くことになる。手順書は実行用に細かく書かれているため、工程だけを知りたい人には長すぎる。

二重に持つと、ずれる。 これは分かったうえで受け入れている。代わりに、ルールにこう書いておく。

手順を変えるときは2箇所を必ず揃える。 食い違いを検知する仕組みは無い。章構成を変える作業では、両方を開く。

粒度も揃える。片方だけ細かくすると、比べたときにどちらが正しいか分からなくなる。

「二重管理は避ける」は原則として正しいが、原則を貫くコストが利益を上回る場所がある。 そういう場所は、例外にしたうえで、なぜ例外なのかと、ずれたときにどうするかを書いておく。黙って例外にすると、後から見た人が「統一されていない」と判断して片方を消す。

5. 止まる場所を記号で示す

動作フローで最も重要なのは、どこでユーザーの回答を待つかになる。ここが分からないと、AIは確認せずに最後まで走り切る。

記号を2つ決めている。

2つを混ぜない。 どちらも「止まる」ではあるが、性質が違う。★は待つだけで、答えれば続く。■はそこで終わりになる。

分けている実務上の理由がある。動作フローの図の直後に「★の3箇所で必ず止まる」という一文を置いているためで、ここで数えるのは★だけになる。■を混ぜると、数が合わなくなる。■は別の一文で説明する。

数を書いておくと、確認ができる。 手順書を直したあとに図を見て、★の数が一文と合っていれば整合している。合っていなければ、どこかを直し忘れている。

6. 自分で作る手順

手順1:型にする作業を1つ選ぶ

最初から複数を作らない。 1つ作ってみないと、何を書けばよいかの感覚が掴めない。

選ぶ基準は3つになる。

• 週1回以上やっている
• 手順がだいたい決まっている
• 出てくるものの良し悪しを、自分で判断できる

3つ目が大事になる。良し悪しを判断できない作業を型にすると、間違った手順が固定される。

手順2:今やっている手順をそのまま書き出す

理想の手順ではなく、今やっていることを書く。「本当はこうすべき」を書き始めると、実際にはやらない工程が混ざる。

AIに書き出させてよい。

「先週このやり取りでやった作業を、手順として書き出して」

過去の会話を読ませて起こさせると、自分では意識していなかった工程が出てくる。

手順3:止まる場所を決める

書き出した手順を見て、人間が判断すべき場所に印を付ける。

判断の基準は「間違っていたときに取り返しがつくか」になる。取り返しがつかないもの——公開する、送信する、削除する——の直前は止める。取り返しがつくものは止めない。止まる場所が多すぎると、呼び出す意味がなくなる。

手順4:手順書として保存する

Claude Codeであれば .claude/skills/<コマンド名>/SKILL.md に置くと、/コマンド名 で呼び出せる。他のツールでも、決まった場所に置いて呼び出す仕組みがあることが多い。

目次の直後に動作フローを置く。 全工程を並べ、止まる場所に★を付ける。図の直後に「★の3箇所で必ず止まる」と数を書く。

手順5:設計資料4ファイルを作る

skills設計/<コマンド名>/ に4ファイルを作る。

最初は設計書.md と変更履歴.md の2つだけでよい。設計判断.md は書くべき判断が生まれてから、今後の課題.md は制約が見つかってから足す。空のファイルを4つ並べても、埋める動機がない。

ただし4ファイル置くと決めておく。決めておかないと、判断が生まれたときに設計書へ書き足してしまう。

手順6:使いながら直す

一度で完成させない。使って、詰まったところを直す。直すときは2章の更新順を守る。

変更履歴を先に書く。 ここを飛ばすと、数か月後に「なぜこの工程があるのか」が分からなくなり、消して、また困ることになる。

効いているかの確かめ方

2回目の実行で分かる。指示を書かずに /コマンド名 だけで、1回目と同じ品質のものが出てくれば型になっている。

補足の指示を毎回足しているなら、その補足は手順書に入るべきものになる。毎回足している一文は、手順書に足りない一文になる。

7. この連載のまとめ

4つのルールが揃った。それぞれの担当範囲を並べると、重なりがないことが分かる。

4つは独立しているようで、つながっている。

• 「資料の書き方をそろえる」で各ファイルの冒頭から追い出した「他ファイルとの関係」を、「置き場所をそろえる」の索引が受け取る
• 同じく本文から追い出した「変更の経緯」を、この回の変更履歴.md が受け取る
• 「意図しない課金を止める」だけは他とつながらない。外部との境界を守るだけで、内側の作りには関与しない

どれか1つだけ採り入れる場合は、①を選ぶ。 単独で成立し、決めた瞬間から効く。

2つ目を足すなら②になる。 ③は②が前提になり、④は②③が整っていると作りやすい。逆順で作ると、置き場所が決まっていないのに手順だけがある状態になる。

全部を一度に作らない

4つとも、困ったから作ったものになる。①は自動化の提案が出てきたとき、②は資料が20を超えたとき、③はどこに何があるか分からなくなったとき、④は同じ指示を3回貼ったとき。

困っていないルールは、書いても守られない。 守る理由が実感できないためになる。困ってから書けば、なぜそうしたかが自分の中に残っている。その理由を書き残せるのは、困った直後だけになる。

ルールの分量も、困りごとの大きさに合わせてよい。「意図しない課金を止める」のルールは50行に満たないが、それで足りている。目的が1つなら、条文も1つで済む。

次に向かう先

ここで作ったのは土台になる。AIと同じ資料を扱う前提が揃った状態で、実際の作業をどう組み立てるかは活用事例の他の記事で扱う。

作った4つのルールは、そのまま置いておけば効き続けるものではない。使っていると必ず、ルールに書いていない事態が来る。そのときに足せばよい。足せる形になっていることが、この連載で作ったものの本体になる。

← ③ 置き場所をそろえる