archive

archiveスキルの概要

archiveが得意なこと

archive スキルは、その場限りのセッション知識を再利用できるプロジェクトの記憶に変えたいチームや個人開発者向けの仕組みです。修正内容をチャット履歴に埋もれさせる代わりに、デバッグの解決策、デプロイ時の注意点、作業プロセスの学びを .archive/YYYY-MM-DD/ に構造化された markdown として保存し、さらに .archive/MEMORY.md に軽量な索引を残します。

archiveを導入すべき人

この archiveスキルは、インフラ、CI、リリース、デバッグまわりの同じ問題に何度も向き合う人に特に向いています。次に似た作業が来たときの復旧や再判断を速くしたいなら、相性が良いです。複数セッションにまたがる仕事、複数エージェントで進む作業、あるいは複数メンバーが「前回どうだったか」を共有しておきたい現場では、とくに効果を発揮します。

本当に解決したい仕事

ユーザーが必要としているのは、新しいメモ習慣そのものではありません。重要なタスクが終わった直後に価値の高い技術的コンテキストを確実に残し、次に似た作業を始める前にその情報をすぐ引き出せることです。archive は汎用ドキュメント作成ではなく、その運用フローに合わせて設計されています。

archiveが普通のプロンプトと違う理由

通常のプロンプトでも、AIに「今回やったことを要約して」と頼むことはできます。ですが archive スキルには、繰り返し使える保存パターン、必須のメモリ索引更新、さらに .archive/MEMORY.md が存在する場合はセッション開始時に自動読み込みするフックがあります。これにより、Knowledge Bases向けの archive は実運用しやすくなります。単に markdown ファイルを残すのではなく、次回の作業コンテキストの一部として生きるからです。

導入前に知っておきたい主なトレードオフ

archive は意図的にシンプルです。データベース、ベクトル検索、自動分類パイプラインは備えていません。価値の源泉は、規律あるファイル構造、検索しやすいタグ、そしてメモリ索引にあります。チームで .archive/MEMORY.md を継続的にメンテナンスできないなら、archiveスキルの強みはかなり薄れます。

archiveスキルの使い方

archiveの導入手順と最初に読むべきリポジトリ内ファイル

実用的な archive install の進め方は次の通りです。

1. スキルシステムに ReScienceLab/opc-skills リポジトリからこのスキルを追加する。
2. まずワークフロー確認のために skills/archive/SKILL.md を読む。
3. 次に必要なアーカイブ形式を把握するため skills/archive/references/TEMPLATE.md を読む。
4. セッション開始時のコンテキスト読み込みが気になる場合は skills/archive/hooks/hooks.json と skills/archive/hooks/load-memory.py を確認する。
5. 想定されている挙動を確認するために skills/archive/.factory-plugin/plugin.json を見る。

補助ファイルを1つだけ流し読みするなら、references/TEMPLATE.md を優先してください。何が「良い archive出力」なのかが最も分かりやすくまとまっています。

archiveスキルに必要な入力

archiveスキルは、次の情報を渡すと特にうまく機能します。

• 完了したタスクまたは発生したインシデント
• 主な結果
• 実施した重要なステップ
• 重要なコマンド、設定変更、またはコード上の判断
• どこで失敗し、最終的にどう直したか
• カテゴリと想定タグ
• 関連しそうな過去の archiveエントリ

ここが曖昧だと、あとで役に立たないぼんやりした archive になりがちです。

archiveを使うべきタイミング

archive は次のようなタイミングで使うのが適しています。

• デプロイが成功した後
• 難しいデバッグ対応が終わった後
• マイグレーションやインフラ変更の完了後
• 大きな機能実装の完了後
• ユーザーから「archiveして」と指示されたとき

細かな修正すべてに使う必要はありません。このスキルが対象にしているのは、長く残す価値のある学びであって、ノイズの多い作業ログではありません。

実務でのarchive運用フロー

想定されている流れは次の通りです。

1. .archive/MEMORY.md を見て、関連する過去の記録がないか確認する。
2. .archive/YYYY-MM-DD/ を新規作成するか、既存のものを使う。
3. テンプレート構造と YAML frontmatter に沿って markdown の archive を作成する。
4. .archive/MEMORY.md に1行の索引エントリを追加する。
5. related フィールドで関連エントリ同士をつなぐ。

この索引更新は、形式的な作業ではありません。後から素早く見つけられるようにするための重要な工程です。

archiveスキル向けの、より良いプロンプト

弱いプロンプト:

• “Archive this session.”

より良いプロンプト:

• “Use the archive skill to document today’s ECS deploy issue. Include the IAM permission error, the CloudWatch clue, the exact fix, final deploy status, tags for ecs, iam, deploy, category infrastructure, and add a one-line entry to .archive/MEMORY.md. If a related archive exists, link it.”

後者のように依頼すると、実際に再利用できる archive を作るための構造がモデルに十分伝わります。

ラフな目的を完全なarchive依頼に変える方法

元の目的が「学んだことを保存したい」程度の粗いものなら、次の観点まで広げて依頼すると archive の質が上がります。

• 何が起きたのか
• なぜ重要だったのか
• 何が失敗したのか
• 何が解決につながったのか
• 次回は最初に何を確認すべきか
• どのカテゴリに入れるべきか
• 後でどういうタグで見つけられるべきか

このスキルが評価するのは物語的な文章ではなく、検索・再取得を前提にした書き方です。

archiveテンプレートで特に重要な項目

references/TEMPLATE.md の中でも、とくに重要なのは次の項目です。

• tags: grep ベースで見つけるための軸
• category: 索引を整理するための軸
• related: 時系列をまたぐ関連インシデントを結ぶための軸

本文では、たいてい次のセクションの価値が高くなります。

• Summary
• Issues Encountered & Solutions
• Key Changes

具体的な修正内容を省くと、archive の実用性は大きく落ちます。

セッション開始時のメモリフックが使い方をどう変えるか

このフックは、.archive/MEMORY.md が存在するとセッション開始時にその内容をコンテキストへ読み込みます。つまり archiveスキルは「書くため」だけのものではなく、将来の想起を自動で強化する仕組みでもあります。導入判断の観点では、単発のメモファイル運用ではなく、あえて archiveスキルを入れる理由のひとつがここです。

Knowledge Bases向けarchiveとチームの記憶

Knowledge Bases向けの archive では、.archive/MEMORY.md を目次、日付付きの各 markdown ファイルをインシデントや作業記録の本文として捉えると分かりやすいです。特に相性が良いのは次のような内容です。

• 繰り返し起きる運用トラブル
• 落とし穴付きのリリースチェックリスト
• 環境固有の修正
• 後から影響が出る設計判断

一方で、広範なプロダクト文書やユーザー向けマニュアルにはあまり向いていません。

実践的な検索・参照フロー

このスキルは、軽量な検索手順を前提にしています。

• .archive/MEMORY.md を確認する
• grep -ri "keyword" .archive/ を使う

保存される内容が限定的で、技術寄りで、構造化されているため、多くのエンジニアリングチームではこれで十分です。タグには、あとで本当に検索される語を使ってください。たとえばサービス名、エラー文字列、プラットフォーム名、コンポーネント名などです。

archiveスキル FAQ

すでにメモを書いていてもarchiveを入れる価値はある？

あります。今のメモが見つけにくい、あるいは次のエージェント作業時にコンテキストへ戻ってこないなら、archiveスキルを入れる意味は十分あります。保存場所、構造、索引、セッション開始時のメモリ読み込みを標準化できるのが強みです。

このarchiveスキルは初心者でも使いやすい？

はい、基本的には使いやすいです。ワークフロー自体は markdown と1つの索引ファイルが中心でシンプルです。初心者がつまずきやすいのは、要約が抽象的すぎることです。テンプレートをそのまま使い、具体的な修正、コマンド、学びを埋めていく運用だと使いやすくなります。

archiveを使わないほうがいいのはどんなとき？

archive は次の用途には向きません。

• ささいな編集
• 一時的なブレインストーミング
• 長文の正式ドキュメント
• README.md や runbooks のような恒久的なリポジトリ文書に置くべき知識

その情報が常に全員の行動を導くべきものなら、.archive/ だけに置くのではなく、標準ドキュメントに載せるほうが適切な場合があります。

archiveは通常のプロジェクト文書と何が違う？

通常のドキュメントは「本来どうあるべきシステムか」を説明します。archive運用が記録するのは、タスクやインシデントで実際に何が起きたかです。失敗した経路、正確な修正内容、そして普通は失われがちな判断コンテキストを残します。これは正本ドキュメントの代替ではなく、履歴ベースの運用メモリ層です。

archiveに特別なツールは必要？

ほとんど必要ありません。中核になるのは markdown ファイル群と .archive/MEMORY.md です。リポジトリにはセッション開始時にメモリを読み込むフックも含まれていますが、それがなくても archiveスキルは規律ある保存パターンとして十分機能します。

このarchiveガイドがカバーする範囲

この archiveガイドは、リポジトリが実際にサポートしている範囲に基づいています。具体的には、ファイルベースのアーカイブ、索引付きメモリ、シンプルなカテゴリ、関連リンク、フックによる再想起です。自動要約パイプライン、セマンティック検索、外部ナレッジベース同期までを約束するものではありません。

archiveスキルを改善する方法

ストーリーとしてではなく、再取得しやすいarchiveを書く

良い archive 出力は、後から見返したときに素早く要点を拾えます。問題、修正、重要なコマンドを、未来の読み手がすぐ見つけられる位置に置いてください。きれいな物語よりも、ぶっきらぼうでも検索しやすい記録のほうが価値があります。

本当に検索されるタグを使う

良いタグ:

• サービス名やツール名
• 正確なサブシステム名
• デプロイ先プラットフォーム名
• エラーのキーワード
• 影響を受けた環境名

悪いタグ:

• issue、work、update のような曖昧な語

これは archive運用品質を大きく左右する、効果の高い改善ポイントです。

MEMORY.mdを儀式ではなく実用品にする

弱い索引エントリの例:

• “Fixed deployment issue”

強い索引エントリの例:

• “ECS deploy failed due to missing IAM permission for secret access; resolved by updating task role policy”

索引は、次にどの archive を開くべきか判断できる内容になっているべきです。

将来の判断に影響するなら、失敗した試行も残す

正しい修正にたどり着く前に、チームが2つの誤った対処を試していたなら、同じ無駄を繰り返さないためにそれも記録する価値があります。こうした行き止まりを残せる点は、archiveスキルが通常のドキュメントより優れている場面のひとつです。

より良いarchive出力のために、入力を具体化する

archive を依頼する前に、次の情報をそろえておくとよいです。

• 正確なエラーテキスト
• 関連するコマンド
• 変更したファイルや設定
• 最終的に確認できた状態
• なぜその修正が効いたのか

こうした具体情報は、将来の再利用性と検索性を実質的に高めます。

archiveスキル運用でよくある失敗パターン

典型的な問題は次の通りです。

• .archive/MEMORY.md の更新漏れ
• 汎用的すぎるタグ
• 明確なカテゴリがない
• 運用の実態がない要約だけの記録
• 過去インシデントとのつながりがない archive エントリ

archive の出来が悪くなる原因の多くは、テンプレートそのものではなく、入力不足にあります。

最初のarchiveドラフト後に見直す

最初のドラフトを書いたら、次を確認してください。

• 想定される検索語で見つけられるか？
• 要約に結果と原因が入っているか？
• 重要なコマンドや設定変更が含まれているか？
• 将来のエージェントは最初に何を試すべきか分かるか？
• 古い関連エントリへのリンクを付けるべきか？

短い2回目の見直しだけでも、archive の質はかなり上がります。

恒久ドキュメントの代わりではなく、archiveを併用する

今回のセッションから恒久的なルールが見えたなら、正本のドキュメントも更新してください。archiveスキルはイベント単位の知識を残すためのものであり、重要なチーム指針の唯一の置き場になるべきではありません。

archive導入を定着させるには、チームで明確なトリガーを決める

チーム運用では、次のような明確なトリガーを決めておくと archive の成果が安定します。

• 想定外があった本番デプロイごと
• すぐには分からない修正が必要だったインシデントごと
• すべてのマイグレーション
• 「次回のために残して」とユーザーに言われたケースごと

こうしておくと、ノイズで埋めずに archive の価値を保てます。