【ITニュース解説】3 Weekly Runs, 3 Failures: My "Fixed" Claude Code Skill Auto-Update Failed Silently for 3 Weeks

ある開発者が、自分が作った自動更新の仕組みが、知らぬ間に長期間にわたって機能していなかったという経験を語る。この件は、システムエンジニアを目指す皆さんにとって、日々の開発や運用で陥りやすい落とし穴や、見落としがちなポイントを教えてくれるだろう。

この自動更新システムは、開発者が利用する「Claude Code」というAIツールのスキルを常に最新の状態に保つためのものだった。毎週日曜日の早朝に、macOSに備わる「launchd」という自動実行機能を使ってシェルスクリプトが起動し、「npx skills@latest update -g」というコマンドを実行する仕組みである。しかし、このコマンドにはいくつかの弱点があった。一つは、GitHubのAPI（アプリケーション・プログラミング・インターフェース）にアクセスする際に、認証されていない状態だとすぐに「レート制限」に引っかかってしまうことだ。レート制限とは、一定の時間内に利用できる回数に上限があることで、これを超えると一時的にアクセスがブロックされる。もう一つは、ネットワークの状態が悪い時に、処理が途中で停止してしまう（ハングアップする）可能性があったことである。このような問題が放置されると、いくら自動更新を設定していても、スキルは全く更新されなくなるという状況に陥ってしまう。

以前、開発者はこれらの問題を解決するために、スクリプトに3つの対策を施していた。一つ目は、GitHubの「認証済みトークン」を利用してAPIにアクセスすることだ。これにより、認証されていない場合の厳しいレート制限（1時間あたり60回）から、はるかに緩い制限（1時間あたり5000回）へと緩和され、更新作業が途切れる可能性を大幅に減らせるはずだった。二つ目は、「gtimeout」というコマンドを使って、更新作業の実行時間に上限を設けることだ。以前はタイムアウトが45秒と短すぎたため、処理が途中で終わってしまうことがあった。そこで、これを10分（600秒）に延長し、ハングアップしていつまでも処理が終わらない状況を防ぐようにした。三つ目は、「STAMP」という最終成功時刻を記録するファイルを、更新が「成功した場合のみ」更新するように変更したことである。これまでの仕組みでは、失敗してもSTAMPファイルが更新されてしまい、問題が隠れてしまうことがあった。この変更によって、失敗した場合はSTAMPが古いままで残るため、一目で問題が起きていることがわかるようにする狙いだった。これらの修正は、過去の確認作業で「4分00秒で成功し、正常終了した」と記録されており、開発者はこれで問題は完全に解決したと信じていた。

しかし、実際の運用状況は、開発者の期待とは大きく異なっていた。自動更新が失敗した際に記録されるエラーログ（skills-update.err）を確認すると、9月6日、9月13日、9月20日と、3週連続で毎週日曜日の決まった時刻に「skills update failed (timeout or error)」というメッセージが記録されていたのだ。これは、更新作業がタイムアウトするか、何らかのエラーによって失敗し続けていたことをはっきりと示している。さらに、更新成功時にのみ更新されるはずのSTAMPファイルの最終更新時刻を見ると、自動実行されるはずの毎週日曜日の午前4時40分とは全く異なる、9月10日の午後5時2分という日付になっていた。このことから、最後に更新が成功したのは、自動実行によるものではなく、おそらく開発者が手動で実行した時だった可能性が高いことが判明した。つまり、この3週間の自動更新は一度も成功しておらず、STAMPファイルは3週間以上も更新されずに放置されていたのである。

では、なぜこれほど入念に施された「修正」が、根本的な解決に至らなかったのだろうか。驚くべきことに、導入された3つの安全対策は、それぞれ設計通りに機能していたことがわかった。gtimeoutコマンドは正しく動作し、処理が10分以内に終了したため、無限のハングアップを防げた。成功時のみSTAMPファイルを更新する仕組みも期待通りに機能し、更新が成功しなかったためSTAMPは更新されなかった。そして、エラーが発生した際には、しっかりとエラーログに記録を残していた。つまり、これらの安全対策は「静かに起きる失敗」を「ログに記録される失敗」に変えることには成功したが、肝心な「更新が失敗する根本原因」そのものは取り除いていなかったのだ。開発者は、最も疑わしい点として、GitHubの認証トークンを取得する「gh auth token」コマンドの挙動を挙げている。このコマンドが、launchdのようなユーザーが直接操作しない（非対話型）環境や、早朝でキーチェーン（パスワードなどを安全に管理する仕組み）がロックされている可能性がある状況で、常にGitHubの認証トークンを正しく取得できるかどうかは保証されていなかった。もしトークンが取得できなかった場合、スクリプトは警告を出すことなく、認証されていないAPI利用経路に静かに戻ってしまう。その結果、元々回避しようとしていたレート制限の問題に再び直面し、更新が失敗していた可能性が考えられる。また、以前に作成された、gtimeoutの導入を促す自動生成スキルも、「gtimeoutコマンドが存在すること」しか検証しておらず、「そのコマンドが使われた結果、ジョブが実際に成功するか」までは検証範囲外だったことも、この問題を見過ごす一因となった。

この経験から、開発者はいくつかの重要な教訓を得ている。一つは、単純にタイムアウト時間を延ばすだけでは、ネットワークの問題やレート制限といった根本原因は解決しないということだ。タイムアウトはハングアップ対策にはなるが、根本的な問題には対処できない。二つ目は、成功時のみ更新されるSTAMPファイルやエラーログが整備されていても、それを定期的に確認しなければ意味がないということだ。ログに失敗が記録されていても、誰もそれを見なければ「数ヶ月間何も更新されていない」という状況に逆戻りしてしまう。三つ目は、「トークンが取得できなくても以前と同じように動く」といったフォールバック（代替処理）の設計には細心の注意が必要だということだ。認証が成功したかどうかをログに記録しないと、本来の修正がひっそりと機能しなくなっていても気づけない。さらに、STAMPファイルの最終更新時刻が自動実行のスケジュールと一致しない場合は、自動実行パスで成功していない可能性が高い。そして、既存の検証スキルが「コマンドが存在すること」だけをチェックしていても、「そのコマンドを使ったジョブが継続的に成功すること」は別の検証が必要な事柄だということを改めて認識した。

結局のところ、今回の一件は、システムが「設計通りに動く」ことと「実際に期待通りに動く」ことの間には大きな隔たりがあることを示している。コードのコメントや過去の測定結果が「問題なし」と示していても、それはある時点での真実に過ぎず、その後の状況変化に対応し続けるとは限らない。自動化されたバックグラウンドジョブが意図通りに機能し続けているかどうかを定期的に確認し、実際のログや動作状況と突き合わせることが、システムエンジニアにとって非常に重要だという教訓である。開発者は今後、認証トークンの取得に関する問題をさらに深く掘り下げ、真の根本原因を特定しようとしている。