Claude Code開発設定
こんな状況に遭遇したことはありませんか？
- 新しいセッションを開くたびに、Claudeにプロジェクトの命名規則をもう一度説明しなければならない
- Claudeが突然、ファイル削除などの危険なコマンドを実行してしまう
- Claudeにコードレビューをさせたら、プロジェクト全体をコンテキストに詰め込んでしまい、遅くてコストも高い
- あなたが丹念に作り上げたClaudeの使い方を、新しい同僚がまったく再利用できない
これらの問題は、Agent Development Kit（ADK、エージェント開発キット）と呼ばれる構造で解決できます。
その中核は5つのフォルダです。この5つのフォルダによって、Claude Codeを記憶を持ち、ルールを理解し、役割分担ができ、複製可能な自動化開発チームに変えることができます。
全体構造：
你的项目/ ├── CLAUDE.md/ ← 第一层：记忆 ├── skills/ ← 第二层：知识 ├── hooks/ ← 第三层：护栏 ├── subagents/ ← 第四层：分工 └── plugins/ ← 第五层：复制
| 階層 | ディレクトリ / ファイル | 役割 | 核心的な意味 | 類推による理解 |
|---|---|---|---|---|
| 第1層 | CLAUDE.md/ |
エージェントのグローバルルールと記憶センター | AIの行動規範、プロジェクト背景、開発制約を定義する | AIプロジェクト操作マニュアル |
architecture.rules |
アーキテクチャルールの定義 | コード構造、命名規則、ディレクトリ設計を規定する | 技術チームのコーディング規約 | |
global.md |
グローバル共有メモリ | すべてのプロジェクトに有効な長期ルール | AIの長期記憶 | |
project.md |
現在のプロジェクト専用のメモリ | 現在のリポジトリのビジネス背景、特別な要件 | プロジェクトREADMEの拡張版 | |
| 第2層 | skills/ |
スキルモジュールディレクトリ | AIに専門能力を注入する | AIのスキルライブラリ |
SKILL.md |
スキル説明ファイル | AIにどのような場合にそのスキルを呼び出すかを伝える | スキル説明書 | |
scripts/ |
スキルスクリプトディレクトリ | 自動化スクリプトとテンプレートを格納する | ツールボックス | |
context.md |
スキルコンテキスト | スキル実行時に必要な背景知識を提供する | 専門知識ベース | |
| 第3層 | hooks/ |
Hookフックシステム | 実行前後にチェックロジックを自動挿入する | 自動セキュリティ監査 |
PreToolUse.sh |
ツール実行前フック | コマンド実行前に検証を行う | 「危険操作確認器」 | |
PostToolUse.sh |
ツール実行後フック | 実行完了後に自動処理する | 自動フォーマット、通知 | |
SessionStart.sh |
セッション起動フック | 開発環境を初期化する | IDE起動スクリプト | |
| 第4層 | subagents/ |
サブエージェントディレクトリ | 異なる専門分野のAgentに分割する | AIチーム協業システム |
code-reviewer.md |
コードレビューAgent | コードReviewを専門に担当する | Reviewerエンジニア | |
test-runner.md |
テストAgent | テストを自動実行する | QAテストエンジニア | |
explorer.md |
探索型エージェント | コードベース構造を分析する | 技術調査担当 | |
| 第5層 | plugins/ |
プラグインシステム | 能力をモジュール化して配布する | AIアプリマーケット |
manifest.json |
プラグイン設定マニフェスト | プラグインのメタデータを定義する | npm package.json | |
marketplace.url |
プラグインマーケットのアドレス | プラグインのダウンロードと共有の入り口 | アプリストア | |
team.install |
チームインストールスクリプト | ワンクリックでチーム環境を同期する | DevOps初期化スクリプト |
各層がそれぞれ1つの具体的な問題を解決します。以下で一つずつ詳しく解説します。
第1層：CLAUDE.md— Claudeに長期記憶を取り付ける
問題は何か？
Claudeにはセッションをまたぐ記憶がありません。今日、コンポーネントの命名はアッパーキャメルケースだと伝えても、明日新しいセッションを開くと忘れてしまいます。
解決策
プロジェクトに1つのファイルを置きますCLAUDE.mdファイルに、繰り返し説明したくないことをすべて書き込みます。セッション開始時にClaudeが自動的にそれを読み取ります。
2つのファイル、2つの適用範囲：
| ファイルの場所 | 適用範囲 |
|---|---|
~/.claude/CLAUDE.md |
あなたのコンピュータ上のすべてのプロジェクトで有効 |
プロジェクトのルートディレクトリ.claude/CLAUDE.md |
に対してのみこのリポジトリのみ有効 |
何を書くのか？Claudeに最もよく繰り返している言葉を考えてみてください：
# 项目：我的电商平台 ## 技术栈 - 前端：Next.js 14（App Router） - 样式：Tailwind CSS - 数据库：PostgreSQL + Prisma ## 命名规范 - 组件文件：大驼峰，如 `UserCard.tsx` - 工具函数：小驼峰，如 `formatPrice.ts` - API 路由：短横线，如 `/api/user-profile` ## 注意事项 - 禁止使用 `any` 类型 - 所有异步函数必须有 try/catch - 提交代码前必须通过 ESLint 检查 - 不要直接操作 `main` 分支 ## 代码风格 - 缩进：2 个空格 - 引号：单引号 - 函数优先用箭头函数
効果：毎回の会話の冒頭で長い背景説明を貼り付ける必要がなくなります。
第2層：skills/— あなたの経験を保存する
問題は何か？
Claudeに新しいコンポーネントを書いてもらうたびに、毎回やり方が異なることがあります。テストを追加するときもあれば追加しないときもあり、TypeScriptの型があるときもあればないときもあります。
解決策
標準的なやり方をスキルファイルとして書き、次の中に置きますskills/ディレクトリ。Claudeはタスクの説明に基づいて、自動的にマッチングして呼び出します対応するスキルを。コマンドを入力する必要はありません。
ディレクトリ構造：
skills/ ├── SKILL.md ← 技能索引（描述 + 触发条件） ├── create-component.md ← 创建 React 组件的标准流程 ├── write-api.md ← 写接口的标准流程 └── fix-bug.md ← 排查 Bug 的标准流程
スキルファイルはどのようなものか？
---
name: create-react-component
description: >
当用户说"创建组件"、"新建页面"、"写一个 UI"时，
自动调用此技能。
---
# 创建 React 组件的标准流程
## 步骤
1. 检查 `src/components/` 下是否已存在同名组件
2. 用大驼峰命名新建 `.tsx` 文件
3. 必须定义 TypeScript interface，不允许 any
4. 同步在 `src/stories/` 下新建对应的 Storybook 故事
5. 在 `__tests__/` 下新建单元测试文件
## 代码模板
\`\`\`tsx
interface Props {
// 在这里定义 props
}
export const ComponentName: React.FC<Props> = ({ }) => {
return <div>{/* 内容 */}</div>;
};
\`\`\`
効果：「ユーザーカードコンポーネントを作成して」と言うだけで、Claudeはチームの標準プロセスに従って自動的に実行し、テスト、型、ドキュメントを漏れなく作成します。
💡 わかりやすく言うと：これは新入社員に『操作マニュアル』を渡すようなものです。マニュアルに従って仕事をするので、毎回あなたが監視する必要はありません。
第3層：hooks/— 迂回できないガードレールを設置する
問題は何か？
AIが時として、あなたが絶対に望まない操作を行うことがあります。例えば本番環境でデータベースを直接削除したり、次のようなコマンドを実行したりrm -rfコマンドです。このようなことは、プロンプトで「やらないで」と伝えるだけでは信頼性がありません。
解決策
Hooksは、Claudeのツール呼び出しの前後に自動実行されるShellスクリプトです純粋なコードロジックで決定的に実行されるため、AIは迂回できません。
3つの核心ファイル：
hooks/ ├── PreToolUse.sh ← 工具调用「之前」运行 ├── PostToolUse.sh ← 工具调用「之后」运行 └── SessionStart.sh ← 会话「开始时」运行
PreToolUse.sh の例 — 危険なコマンドをインターセプト：
#!/bin/bash # 检查 Claude 准备执行的命令 TOOL_INPUT="$2" # 禁止执行 rm -rf / if echo "$TOOL_INPUT" | grep -qE "rm\s+-rf\s+/"; then echo "已拦截：禁止执行破坏性删除命令" >&2 exit 1 fi # 禁止在没有确认的情况下操作生产数据库 if echo "$TOOL_INPUT" | grep -q "prod_db" && echo "$TOOL_INPUT" | grep -qE "DROP|DELETE"; then echo "已拦截：生产数据库的破坏性操作需要人工确认" >&2 exit 1 fi exit 0
PostToolUse.sh の例 — ファイル保存後に自動フォーマット：
#!/bin/bash
# 每次 Claude 写完文件，自动跑 lint 和格式化
TOOL_NAME="$1"
FILE_PATH="$2"
if [ "$TOOL_NAME" = "write_file" ]; then
case "$FILE_PATH" in
*.ts|*.tsx|*.js|*.jsx)
npx eslint --fix "$FILE_PATH"
npx prettier --write "$FILE_PATH"
echo "已自动格式化：$FILE_PATH"
;;
esac
fi
効果：
- Claudeがコードを書き終えると自動でlintしてくれるので、手動で実行する必要がありません
- 危険なコマンドは実行前にインターセプトされるので、確認する必要すらありません
- デプロイスクリプトが完了すると、自動でSlack通知がチームに送信されます
💡 わかりやすく言うと：工場のラインにおける品質検査のようなものです。製品は出荷前に強制的にチェックされ、規格に合わないものは直接はじかれます。作業員の個人判断には依存しません。
第4層：subagents/— 専門の人に専門の仕事をさせる
問題は何か？
Claudeに1つのセッションで「コードレビュー＋テスト実行＋ドキュメント作成」を同時にやらせると、コンテキストがどんどん大きくなり、どんどん遅くなり、さらにさまざまなタスクが互いに干渉し合います。
解決策
異なるタスクを分割して独立したサブエージェントに割り当てます各サブエージェントは独立したコンテキストウィンドウと専用のツール権限を持ち、1つのことだけを行い、完了したら結果を報告します。
ディレクトリ構造：
subagents/ ├── code-reviewer.md ← 专门做代码审查 ├── test-runner.md ← 专门跑测试 └── doc-writer.md ← 专门写文档
code-reviewer.md の例：
--- name: code-reviewer description: PR 需要代码审查时调用此代理 tools: - read_file # 只允许读文件 permissions: - read_only # 只读权限，绝对不会误操作 --- # 代码审查专用代理 你是一名资深代码审查员。你只会收到 git diff，不需要了解整个项目。 你没有写入权限，只能阅读和分析。 ## 审查清单 - [ ] 有没有硬编码的密钥或密码？ - [ ] 新函数有没有对应的单元测试？ - [ ] TypeScript 类型是否明确，有没有 any？ - [ ] 异步操作有没有错误处理？ - [ ] 有没有遗留的 console.log？ ## 输出格式 1. **总体评价**：一句话说清楚 2. **必须修改**：阻塞合并的问题 3. **建议优化**：非阻塞的改进项 4. **结论**：可以合并 / 需要修改
全体的な動作フロー：
你说："帮我审查这个 PR 并运行测试"
│
├──→ 调用 code-reviewer 子代理
│ 独立上下文，只看 diff，只读权限
│ 返回：结构化审查报告
│
├──→ 调用 test-runner 子代理
│ 独立上下文，有执行测试的权限
│ 返回：测试通过/失败摘要
│
└──→ 主会话汇总结果，上下文始终保持干净
💡 わかりやすく言うと：それは現場監督のようなものです。監督自身はコードを書きませんが、配管工、左官、大工といった専門の職人を抱えています。各自の仕事は各自が担当し、互いに干渉せず、最後に監督が進捗を一括で報告します。
第5層：plugins/— ワンクリックでチーム全員に共有
問題は何か？
あなたは数日かけて上記の4層をすべて調整しました。しかし、新入社員が入社したとき、どうやってこの設定を知るのでしょうか？まさか彼にもう一度設定させるのですか？
解決策
システム全体をプラグインとしてパッケージ化し、新しいメンバーが1つのコマンドを実行するだけで、あなたとまったく同じ Claude Code 作業環境をすぐに手に入れられます。
ディレクトリ構造：
plugins/ ├── manifest.json ← 描述插件包含什么 ├── marketplace.url ← 分享链接 └── team.install ← 一键安装脚本
team.install の例：
#!/bin/bash echo "🚀 正在安装团队 ADK 配置..." # 安装项目级 CLAUDE.md cp ./CLAUDE.md/project.md ./.claude/CLAUDE.md # 安装所有技能 mkdir -p ./.claude/skills && cp -r ./skills/* ./.claude/skills/ # 安装钩子（记得加执行权限） mkdir -p ./.claude/hooks && cp -r ./hooks/* ./.claude/hooks/ chmod +x ./.claude/hooks/*.sh # 安装子代理 mkdir -p ./.claude/subagents && cp -r ./subagents/* ./.claude/subagents/ echo "安装完成！Claude Code 已配置为团队模式。"
新入社員の入社初日：
bash plugins/team.install
完了です。あなたが使っているのとまったく同じ Claude Code です。
💡 わかりやすく言うと：会社の「新入社員PC設定パッケージ」のようなものです。IT部門がイメージを作成し、新人はワンクリックでインストールすれば、環境は既存社員とまったく同じになり、一つずつ手動で設定する必要はありません。
完全フローチャート：5層がどのように連携するか
开发者输入任务
│
▼
CLAUDE.md → 加载项目规范和背景知识
│
▼
skills/ → 匹配任务类型，调用对应工作流
│
▼
hooks/PreToolUse → 执行前检查，拦截危险操作
│
▼
subagents/ → 复杂任务拆分给专属子代理执行
│
▼
hooks/PostToolUse→ 执行后处理，自动格式化/通知
│
▼
plugins/ → 整套配置一键同步给所有团队成员
5層が解決する問題のまとめ
| 層 | フォルダ | どのような問題を解決するか | たとえ |
|---|---|---|---|
| 第1層 | CLAUDE.md/ |
Claude が毎回プロジェクト規範を忘れてしまう | 従業員ハンドブック |
| 第2層 | skills/ |
同種のタスクのやり方が毎回一貫しない | 操作マニュアル |
| 第3層 | hooks/ |
危険な操作を防ぐことができない | パイプライン品質検査 |
| 第4層 | subagents/ |
複雑なタスクでコンテキストが肥大化する | 専門的な役割分担 |
| 第5層 | plugins/ |
設定をチームで再利用できない | 新人入社パック |
クイックスタート：今日できる3つのこと
一度にすべて設定するのが複雑だと感じる場合は、最も効果の高いものから始められます：
ステップ1（5分）：作成してCLAUDE.mdあなたが最も頻繁に Claude に繰り返し伝えるプロジェクトの背景をすべて書き込んでください。
ステップ2（10分）：作成してhooks/PreToolUse.shClaude に実行させたくない危険なコマンドのブロックルールをいくつか追加してください。
ステップ3（30分）：あなたが最も頻繁に行う種類のタスク（例：「コンポーネントの作成」）を最初のskills/ファイルとして書き、チームの標準を積み上げていってください。
残りの層は使いながら追加していけばよく、一度にすべて完了させる必要はありません。
その他の拡張このシステムの名前はAgent Development Kit（ADK）です。5層構造、1つのスタックです。
追加のツールは必要ありません。必要なのは5つのフォルダだけです。