TL;DR
| 項目 | 内容 |
|---|---|
| 🎯 対象 | VS Code拡張機能「Japanese Input for Claude Code」v1.7.4 |
| 😅 やらかし | Guardrails設定のインポート/エクスポートをクリップボードで実装 |
| 💥 問題1 | クリップボードが他の作業で上書きされて設定が消える |
| 💥 問題2 | インポート時に同名テンプレートが重複作成される |
| ✅ 解決 | ファイルベースに変更 + 名前ベースの重複検出＆マージ |
🎬 はじめに
VS Code拡張機能「Japanese Input for Claude Code」の開発者です。
v1.7.1でGuardrails設定のインポート/エクスポート機能を追加したんですが、「クリップボード経由で手軽にやろう」 という安易な判断が見事に裏目に出ました。
実際の問題はクリップボード経由ってことではないんですが・・・。
今回は、その失敗と修正の記録です。
📋 Guardrails機能とは
Claude Code、Codex、Gemini Code Assistなど複数のAIコーディングアシスタントに対して、AI別のプリセット指示を自動挿入する機能です。
例: Claude Code用Guardrails
「日本語で回答してください。コードにはコメントを付けてください。」
この設定をチーム内で共有したい、PCを移行しても引き継けたらいいなということで、インポート/エクスポート機能を実装しました。
😅 v1.7.1: クリップボードで実装した理由
当初の設計思想：
💭 「JSONをクリップボードにコピー/ペーストするだけでいいじゃん」
💭 「ファイル保存ダイアログとか出すの面倒だし」
💭 「SlackやTeamsに貼り付けて共有できて便利！」
実装も簡単でした：
// エクスポート
await vscode.env.clipboard.writeText(JSON.stringify(templates, null, 2));
vscode.window.showInformationMessage('クリップボードにコピーしました');
// インポート
const clipboardText = await vscode.env.clipboard.readText();
const templates = JSON.parse(clipboardText);
10分で実装完了。完璧。リリース。
...と思っていた時期が私にもありました。
💥 問題1: クリップボードは信用できない
発生した事象
- エクスポートボタンをクリック（JSONがクリップボードにコピーされる）
- 「よし、別のPCに持っていこう」とSlackを開く
- 何か別のものをコピーしてしまう（URLとか、コードスニペットとか）
- 別PCでインポートしようとすると... さっきのJSONがない 😇
根本原因
クリップボードは「一時的な置き場所」であって「保存場所」ではない
当たり前のことなんですが、実装しているときは「すぐ貼り付けるでしょ」と楽観的に考えていました。
💥 問題2: 重複テンプレートが無限増殖
これが本当におバカなバグでした。
発生した事象
- Guardrails設定をエクスポート
- 設定を少し編集
- もう一度インポート
- 同じ名前のテンプレートが2つになる 🤦
Before:
- Claude Code (id: abc123)
After:
- Claude Code (id: abc123) ← 元のやつ
- Claude Code (id: xyz789) ← 新しく作られたやつ
根本原因
インポート時の処理がこうなっていた：
// ❌ ダメなコード
for (const template of importedTemplates) {
// IDで存在チェック
if (!existingTemplates.find(t => t.id === template.id)) {
existingTemplates.push(template); // 新規追加
}
}
エクスポート→インポートでIDが変わるので、名前が同じでも「新規テンプレート」として追加されてしまう。
「IDで重複チェック」という発想自体がおかしかった。ユーザーにとって同じものかどうかは「名前」で決まるのに。
✅ v1.7.3-4: 修正内容
修正1: ファイルベースに変更
// エクスポート: ファイル保存ダイアログ
const uri = await vscode.window.showSaveDialog({
defaultUri: vscode.Uri.file('guardrails-settings.json'),
filters: { 'JSON': ['json'] }
});
if (uri) {
await vscode.workspace.fs.writeFile(uri, Buffer.from(JSON.stringify(templates, null, 2)));
}
// インポート: ファイル選択ダイアログ
const uris = await vscode.window.showOpenDialog({
filters: { 'JSON': ['json'] }
});
if (uris && uris[0]) {
const content = await vscode.workspace.fs.readFile(uris[0]);
const templates = JSON.parse(content.toString());
}
メリット:
- 設定が永続化される
- 好きなタイミングでインポートできる
- Git管理してチーム共有も可能
修正2: 名前ベースの重複検出＆マージ
// ✅ 修正後のコード
let added = 0, updated = 0, skipped = 0;
for (const imported of importedTemplates) {
const existing = existingTemplates.find(t => t.name === imported.name);
if (existing) {
// 同名テンプレートが存在 → 内容を更新
existing.content = imported.content;
existing.updatedAt = new Date().toISOString();
updated++;
} else {
// 新規テンプレート → 追加
existingTemplates.push({
...imported,
id: generateNewId() // 新しいIDを発行
});
added++;
}
}
// 結果をフィードバック
vscode.window.showInformationMessage(
`インポート完了: 追加 ${added}件, 更新 ${updated}件`
);
ポイント:
- 名前で一致判定（IDではなく）
- 既存テンプレートは上書き更新
- 新規テンプレートのみ追加
- 処理結果を詳細表示
📊 Before / After
| 項目 | v1.7.1 (Before) | v1.7.4 (After) |
|---|---|---|
| 方式 | クリップボード | ファイル保存/読込 |
| 永続性 | ❌ 上書きで消える | ✅ ファイルとして保存 |
| 重複処理 | ❌ IDで判定→重複発生 | ✅ 名前で判定→マージ |
| フィードバック | 「コピーしました」のみ | 追加/更新件数を表示 |
| 共有方法 | Slack等に貼り付け | ファイルを送付 or Git管理 |
🎓 学び
1. クリップボードを「保存先」にするな
クリップボードは「転送経路」であって「保存場所」ではない。設定のエクスポートのように後で使うかもしれないデータは、ファイルに保存すべき。
2. 重複判定は「ユーザー視点」で考える
内部IDで判定するのはエンジニア視点。ユーザーにとっての「同じもの」は何かを考えれば、名前で判定するのが自然。
3. 処理結果は具体的に伝える
「完了しました」だけでなく「追加 2件, 更新 1件」のように何が起きたかを伝えると、ユーザーは安心できる。
おわりに
書いててアホ過ぎて穴に逃げ込みたくなるんですが・・。
「簡単に実装できる」と「ユーザーにとって使いやすい」は別物ですね。
クリップボードでサクッと実装→2日後にファイルベースに書き直し、という無駄な工数を発生させてしまいました。最初から「設定の永続化」という要件を真面目に考えていれば...。
同じ轍を踏む人が減れば幸いです 🙏