CLAUDE.mdを"設計"するとClaude Codeの出力品質が別物になる — iOS開発×技術記事で実践した7つの設計原則

はじめに

CLAUDE.mdを「とりあえず書いてみた」段階で止まっていませんか？

私はiOSアプリ3本の開発と技術記事70本以上の執筆をClaude Codeで行っていますが、CLAUDE.mdを"設計"し直した前後で、出力品質とやり取りの回数が劇的に変わりました。

この記事では、実際に運用しているCLAUDE.mdをベースに、なぜその書き方が効くのかを7つの設計原則として言語化します。

この記事の対象者

• CLAUDE.mdを書いたことはあるが、効果を実感できていない人
• Claude Codeでの開発効率をもう一段上げたい人
• 実際に運用されているCLAUDE.mdの具体例を見たい人

原則1：冒頭3行で「人格」を決める

CLAUDE.mdの最初の数行は、Claude Codeの応答スタイル全体に影響します。

NG例

# プロジェクト設定
このプロジェクトはSwiftUIで作られたiOSアプリです。

これだと「情報の羅列」になり、Claude Codeの振る舞いが安定しません。

実践例

# プロジェクト設定

## 基本方針

- 日本語で応答する
- 正確さ > わかりやすさ（初心者向けでも正確さを優先）
- 出力は簡潔に。冗長な説明は不要

ポイント: 「何語で話すか」「何を優先するか」「どの程度の粒度で出力するか」の3点を明示する。これだけで毎回の出力トーンが揃います。

原則2：「やること」より「やってはいけないこと」を書く

Claude Codeは「やること」の指示には従いやすいですが、品質事故の多くは「やってはいけないこと」の未定義から起きます。

実践例（Swiftコーディングルール）

### Swiftコーディングルール

- **force unwrap（`!`）禁止** — `guard let` または `if let` で安全にアンラップする
- **`try!` / `as!` 禁止** — `do-catch` または `as?` を使用する
- **`print()` デバッグ禁止** — `Logger`（os.log）を使用する

「!を使うな」と書くだけで、Claude Codeが生成するSwiftコードからforce unwrapがほぼ消えます。「guard letを使え」だけだと、try!やas!はすり抜けます。

設計原則: 禁止ルールは具体的な記法レベルで書く。「安全なコードを書いて」のような抽象指示は効かない。

原則3：「判断基準」を与えて自律性を上げる

Claude Codeに「毎回聞かれる」のは、判断基準がCLAUDE.mdにないから起きます。

NG例

## ビルド手順
xcodebuild -project App.xcodeproj -scheme App build

この書き方だと、ビルドするタイミングもエラー時の対応もClaude Codeが判断できず、毎回確認が飛んできます。

実践例（ビルド自動確認フロー）

### ビルド自動確認フロー

コード変更後、Claude Codeは以下を**自動で実行**する（毎回の確認は不要）。

1. **`project.yml` を変更した場合** → `xcodegen generate` を実行
2. **ビルド確認** → `xcodebuild` でビルドを実行
3. **ビルドエラー発生時** → エラー内容を読み取り、自動で修正を試みる。2回失敗したらユーザーに報告する
4. **ビルド成功後** → 変更内容のサマリーを1行で報告する

設計原則: 「いつ」「何を」「失敗したらどうするか」の3点を書く。これがあるとClaude Codeが自律的に動けるようになり、やり取りの回数が大幅に減る。

原則4：チェックリストで出力品質を安定させる

人間のレビューと同じで、チェックリストがあるとClaude Codeの出力品質は安定します。特に記事作成のような定型作業で効果が大きい。

実践例（記事作成チェックリスト）

### 記事作成チェックリスト

記事を書き終えたら、保存前に以下を順番に確認する。

1. **コード検証**: すべてのコード例をコンパイル・実行し、出力が記事内の記載と一致するか確認
2. **import漏れ**: コード例に必要なimport文がすべて含まれているか確認
3. **出力の再計算**: 期待出力をコード内の値から手動で再計算し、正しいか検証
4. **公式URL**: 「## 参考」セクションに公式ドキュメントのURLを記載したか確認
5. **著者フッター**: 媒体に応じた著者フッターが末尾に記載されているか確認
6. **ファイル命名**: シリーズ記事は `{ジャンル}_{シリーズ名}_{連番}_{トピック}.md` 形式
7. **タグ確認**: Qiitaは5個以内、主要タグ＋ニッチタグを組み合わせる

このチェックリスト導入前は、記事ごとに「import文が抜けてた」「出力が間違ってた」といった手戻りが頻繁に発生していました。導入後はほぼゼロになりました。

設計原則: 繰り返す作業にはチェックリストを定義する。「品質を上げて」ではなく「この7項目を確認して」と書く。

原則5：テンプレートで出力フォーマットを固定する

記事やコードの「型」が決まっているなら、CLAUDE.mdにテンプレートを書いておくとフォーマットのブレがなくなります。

実践例（Qiita記事のフォーマット）

### Qiita記事

- フロントマター: `title`, `tags` を含む
- 演習問題の難易度: ⭐（基本）、⭐⭐（応用）、⭐⭐⭐（チャレンジ）
- 解答は `<details><summary>模範解答</summary>` で囲む
- 著者フッター:
  [@kotaro_ai_lab](https://x.com/kotaro_ai_lab)
  AI活用や開発効率化について発信しています。フォローお気軽にどうぞ！

### note記事

- Markdown記法は使わない（noteはMarkdown非対応）
- 太字（`**`）、見出し記号（`#`）、コードブロック（` ``` `）は使用しない
- 見出し → `【大見出し】` `【小見出し】` で明示

同じ内容でもQiitaとnoteではフォーマットが全く違います。これをCLAUDE.mdに定義しておけば、「Qiita用に書いて」「note用に書いて」の一言で正しい形式の記事が出てきます。

設計原則: 出力先ごとにフォーマットを定義する。「いい感じに書いて」は再現性がない。

原則6：セキュリティルールは「絶対にやってはいけないこと」から書く

セキュリティは「注意してね」では守れません。禁止事項をリスト化することで、Claude Codeが機密情報を出力に含めるリスクを最小化できます。

実践例

## セキュリティルール

### 絶対にやってはいけないこと

- APIキー・シークレット・パスワードをコードや記事にハードコードしない
- `.env`、`Secrets.plist`、`*.p8`、`*.p12` をgit commitしない
- App Store Connect / Apple Developer の認証情報を出力しない

### 記事・SNS投稿

- コード例にAPIキーやトークンを含めない（`YOUR_API_KEY` 等のプレースホルダーを使う）
- スクリーンショットにシークレット・個人情報が写り込んでいないか確認を促す

設計原則: セキュリティルールは最も具体的に、ファイル拡張子レベルで書く。「セキュリティに気をつけて」は何も守らない。

原則7：階層構造で関心を分離する

CLAUDE.mdは1ファイルにすべてを詰め込む必要はありません。ディレクトリごとにCLAUDE.mdを配置して関心を分離できます。

実践例（複数アプリ開発の構成）

workspace/
├── CLAUDE.md              # 全体共通（記事ルール、セキュリティ、SNS設定）
└── ios-apps/
    ├── CLAUDE.md           # iOS/Flutter共通（技術スタック、ビルド手順）
    ├── WorkoutDiary/       # SwiftUI製
    ├── StudyStopwatch/     # SwiftUI製
    └── daily_tips_app/
        └── CLAUDE.md       # Flutter固有の設定

階層	置くべき内容	置くべきでない内容
ルート	言語設定、出力方針、セキュリティ	アプリ固有のビルド手順
プロジェクト共通	技術スタック、コーディング規約	特定アプリのBundle ID
アプリ個別	固有の設定、依存ライブラリ	全アプリ共通のルール

設計原則: 変更頻度と影響範囲で階層を分ける。全アプリに影響するルールをアプリ個別のCLAUDE.mdに書くと、メンテナンスコストが跳ね上がる。

まとめ：7つの設計原則

#	原則	一言で
1	冒頭3行で「人格」を決める	トーンを固定する
2	「やってはいけないこと」を書く	禁止は記法レベルで具体的に
3	「判断基準」を与えて自律性を上げる	いつ・何を・失敗時の3点セット
4	チェックリストで品質を安定させる	「品質上げて」ではなく項目列挙
5	テンプレートでフォーマットを固定する	出力先ごとに型を定義
6	セキュリティは禁止リストで守る	拡張子レベルで具体的に
7	階層構造で関心を分離する	変更頻度×影響範囲で分ける

CLAUDE.mdは「書けば終わり」ではなく、プロジェクトの成長に合わせて設計し続けるものです。最初は原則1〜3だけでも導入してみてください。やり取りの回数が減り、出力品質が安定するのを実感できるはずです。

参考

• Claude Code 公式ドキュメント — Memory
• Swift API Design Guidelines
• CLAUDE.md — Claude Code公式

---

@kotaro_ai_lab
AI活用や開発効率化について発信しています。フォローお気軽にどうぞ！