取得処理は、必要になるたびに1つずつ増えます。最初は3つだったものが、半年後には20を超えている。どれもそれぞれの理由で作られていて、全体を設計した人はいません。
この状態で困るのは、何かを変えようとしたときです。「このデータはどこから来ているのか」「この処理を止めたら誰が困るのか」。答えられる人がいないと、触れなくなります。
対策は一覧を持つことですが、別の場所に文書として書くと必ず古くなります。コードと一緒に置いて、コードから生成できる形にしておくのが現実的です。
一覧に何を書くか
多くを書こうとすると維持できません。変更したときに一緒に直せる量に収めます。経験上、次の項目があれば大半の問いに答えられます。
- どこから — 配信元の名前と URL
- 何を — 取得している内容の一行説明
- いつ — 実行の間隔と時刻
- どこへ — 保存先
- 誰のため — 何に使われているか。ここが空なら止められる可能性がある
- 認証 — 鍵の種類と、どこに置いてあるか（値そのものは書かない）
最後の2つが重要です。使い道が分からない取得は、止めてよいかの判断ができません。認証の場所が分からない取得は、鍵が切れたときに直せません。この2つが空欄のまま担当者が変わると、そこで手が止まります。
from dataclasses import dataclass, fieldfrom datetime import timedelta
@dataclass(frozen=True)class FetchJob: """取得処理の定義。ここが一覧の実体になる。 別の文書に書くと必ず古くなるので、コードと同じ場所に置く。"""
name: str source: str # 配信元の名前 source_url: str description: str # 何を取っているか interval: timedelta destination: str # 保存先 used_by: list[str] # 誰が使っているか。空なら棚卸しの対象 auth: str | None = None # 鍵の種類と置き場所。値そのものは書かない owner: str = ""
def is_orphan(self) -> bool: """使い道が記録されていない取得。止められる候補。""" return not self.used_by認証の欄には、なのかなのかなのかを書きます。置き場所はの名前まで書いておくと、切れたときにすぐ辿れます。
保存先の欄には、のどこに置いているかを書きます。ここが分かれば、止めたときに何が更新されなくなるかも分かります。取得と保存先が1対1になっていると、この欄が意味を持ちます。
一覧から表を作る
定義をコードに持たせておけば、そこから一覧表を作れます。人が読む形は生成することにして、手で書き写さないようにします。書き写した瞬間から、2つの情報源がずれ始めます。
def render_inventory(jobs: list[FetchJob]) -> str: """定義から表を作る。ここを唯一の出典にする。""" lines = ["| 名前 | 配信元 | 間隔 | 保存先 | 用途 | 認証 |", "|---|---|---|---|---|---|"] for j in sorted(jobs, key=lambda x: x.name): used = " / ".join(j.used_by) if j.used_by else "**不明**" auth = j.auth or "不要" hours = j.interval.total_seconds() / 3600 lines.append( f"| {j.name} | {j.source} | {hours:.0f}時間 | {j.destination} | {used} | {auth} |" )
orphans = [j.name for j in jobs if j.is_orphan()] if orphans: lines += ["", f"用途が記録されていない取得: {', '.join(orphans)}"] return "\n".join(lines)一覧に書くのは種類と置き場所だけです。「APIキー、環境変数 EXAMPLE_API_KEY」で十分。値そのものを書くと、一覧が機密文書になり、共有できなくなります。共有できない一覧は、無いのと同じです。
止まったときに誰が困るか
一覧の中で最も価値があるのは「誰のため」の欄です。これがあると、障害のときに影響範囲が即座に分かります。取得が止まったとき、影響を受ける人に先に伝えられる。
この欄は、作った当初は書けます。時間が経つと分からなくなります。だから作るときに書くしかありません。後から埋めようとすると、結局その処理を止めてみて誰が困るかを確かめる、という乱暴な方法になります。
引き継ぎの観点は エンジニアの引き継ぎ術 でも扱っています。次回は、この一覧を使って取得を減らす話をします。
一覧を作る作業そのものに、副次的な効果があります。書き出してみると、用途が思い出せない取得や、同じデータを2か所から取っている重複が見つかります。作る過程で棚卸しが始まる、ということです。
一覧は、完璧である必要はありません。空欄があってもよいので、まず存在すること。空欄があること自体が「ここは分かっていない」という情報になります。
そして一覧は、担当が変わるときに最も価値を持ちます。引き継ぐ側にとっては、何が動いているのかを知る唯一の手がかりになるからです。
作るときに一緒に書く、という運用が守れるかどうかがすべてです。後から埋める作業は誰もやりません。取得を追加する手順の中に、一覧への追記を組み込んでおくのが確実です。
逆に言えば、一覧に載っていない取得は存在しないものとして扱う、というくらいの割り切りがあってもよいと思います。載せる手間は数分で、載せない代償は数か月後に来ます。
全体像が見えている状態と、見えていない状態では、日々の判断の速さがまったく違います。一覧はそのための道具であって、資料を作ること自体が目的ではありません。維持できる形に留めてください。
把握していないものは、直せませんし、止められません。取得が増えてきたと感じたら、そこが作りどきです。
この記事の感想を教えてください
あなたの 1 クリックで、本当にこの記事は更新されます。「もっと詳しく」「続編希望」が一定数集まった記事は、 ふくふくが 実際に内容を拡充したり続編記事を公開 します。 送信したリアクションはお使いのブラウザに記録され、再カウントされません。