開発環境

6 件の記事

[Claude Code] CLAUDE.md 最適化のための配置ルールの検証

2025-07-23

CLAUDE.mdをどこに配置すれば読まれるのか・読まれないのかを検証しました。

背景

Claude Codeの/initコマンドでCLAUDE.mdを作成すると、プロジェクト全体の要約を詰め込んだCLAUDE.mdがリポジトリルートに作成されます。しかし、このプロジェクト全体の要約は、個別の作業に必要ない情報も多く含まれます。例えばバックエンドのGoのテストを実行するコマンドの情報は、フロントエンドのコーディングをさせるのに必要ありません。

使わない情報を毎回読み込ませるのは無駄であり、各作業の精度低下や無駄なトークン費用の発生につながります。極力CLAUDE.mdは作業に最適化したものを使いたいところです。そのためにはCLAUDE.mdを細分化し、CLAUDE.mdが読まれる条件を把握した上で、それぞれうまく配置する必要があります。

REF: https://www.anthropic.com/engineering/claude-code-best-practices

リポジトリルートに配置したCLAUDE.md

まず基本から。

リポジトリルートに配置したCLAUDE.mdは、サブディレクトリにいようと、同一階層に別のCLAUDE.mdがあろうと、読まれます。

~/repositories/ClaudeCodeTest$ cat CLAUDE.md
# CLAUDE.md

Reply with 'Awesome, Inc.' when asked for the company name.


~/repositories/ClaudeCodeTest$ echo "What is the company name?" | yolo -p
Awesome, Inc.
~/repositories/ClaudeCodeTest$ cd GeneralAffairs/GeneralServices/DocumentManagement/Digitization
~/repositories/ClaudeCodeTest/GeneralAffairs/GeneralServices/DocumentManagement/Digitization$ echo "What is the company name?" | yolo -p
Awesome, Inc.
~/repositories/ClaudeCodeTest/GeneralAffairs/GeneralServices/DocumentManagement/Digitization$ cd ../../../
~/repositories/ClaudeCodeTest/GeneralAffairs$ echo "What is the company name?" | yolo -p
Awesome, Inc.
~/repositories/ClaudeCodeTest/GeneralAffairs$ ls
CLAUDE.md  GeneralServices
~/repositories/ClaudeCodeTest/GeneralAffairs$

※ yolo はClaude Codeのエイリアスです。.bashrcに右記のように設定しています。 alias yolo='claude --dangerously-skip-permissions'

セルフホストランナーのセットアップ

今回はWSL2上のUbuntuで実施。

ただしEC2等のクラウドのインスタンスのほうが安定するので、業務利用ならそちらを推奨します。

手順はこちらのまま。

https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners

GitHub Issueを用いたチケットドリブンとClaude Codeマルチエージェント体制のメモ

2025-06-11

※ まだメモ書きです

🤖 コンテキスト引継ぎの重要ポイント

異なるディレクトリで会話した内容は、同じコンソールで作業しても–continueで引き継がれない
逆にプロセスが異なろうが、同じディレクトリで会話したら–continueで引き継がれる

-> ディレクトリが同じかどうかがキモ

ブランチ作成の前提

親Issue:子Issue = 1:* ( 1つのイシューから0-*の子Issueが作られる。）
Issue(親Issue、子Issueとも):PR = 1:* ( 1つのイシューから複数のPR（プルリクエスト）が作られる）
PR:branch = 1:1 1つのPRに1つの作業ブランチ
branch:agent = 1:1 1つのブランチに1つの担当エージェント
Issue:agent = 1:1 1つのIssueに1つの担当エージェント

また、エージェントの役割の違いは、git worktree add を使って全部ブランチで表現する。

従って、例えばこういうタスク分解がなされ、かつ、各Issueに管理エージェント、各PRにワーカーエージェントが対応してそれぞれ作業を進めることになった場合、

親Issue: API公開
- 子Issue1: インフラ作る
  - PR1: 要件定義
  - PR2: 設計
  - PR3: コーディング
- 子Issue2: コード作る
  - PR4: 要件定義
  - PR5: 設計
  - PR6: コーディング
- 子Issue3: デプロイパイプライン作る
  - PR7: 要件定義
  - PR8: 設計
  - PR9: コーディング

エージェント数と同じだけ必要になるので、13ブランチ必要になる。

ブランチ名

暫定的に

Issueはfeature/<parent_issue_id>とスラッシュ区切りで表す。ただし親Issueがある場合はfeature/<parent_issue_id>/<child_issue_id>とする。なお直上の親Issueだけ書き、その上のIssue以降を書いてはならない。
PRはfeature/<issue_id>/<child_issue_id>/<work_name>のようにIssueのブランチ名に/文字列を加えて表す

とする。またそれとは別にmain(本番用)やdevelopment(開発環境用)、hotfix/X(超急ぎのバグフィックス)などがありえるが、その辺は各流儀に合わせる方向で。

例えばこのようになる。

feature/9             # 親Issue: API公開
feature/9/10          # 子Issue1: インフラ作る
feature/9/10/requirements    # 要件定義
feature/9/10/design         # 設計
feature/9/10/implementation # 実装
feature/9/11          # 子Issue2: コード作る
feature/9/11/requirements
feature/9/11/design
feature/9/11/implementation
feature/9/12          # 子Issue3: デプロイパイプライン作る
feature/9/12/requirements
feature/9/12/design
feature/9/12/implementation

マージ戦略

紐づくブランチにマージする。いきなりmainやdevelopmentに直マージはしない。

Claude Code作業履歴を自動で記録したい実験

2025-06-09

⚠️ 注意: これは実験段階のメモです。実際の検証はまだ行っていません。

背景・課題

現在の問題

Claude Codeを使用してローカルで開発作業を行う際、以下の課題が発生している：

Claude CodeがPRを作成してくれるが、なぜその実装をしたのかの背景情報がGitHub上に残らない
作業過程での判断理由や試行錯誤がローカルにしか保存されず、ほかのメンバー（後日すべてを忘れた自分自身含む）が背景を理解できない

技術的な背景

Claude Codeの会話履歴は ~/.claude/projects/**/*.jsonl にローカル保存される
GitHub上のIssueやPRには、Claude Codeの思考過程や判断理由が記録されない
既存のClaude Code GitHub Actionsは、GitHub Actions上での実行を前提としており、ローカル実行の履歴は対象外

調査結果

既存事例の探索

GitHub OpsでClaude Codeの行動履歴をIssueに集めた事例を調査したが、以下のような状況だった：

アイディア

headless mode: claude -p "<prompt>" --output-format stream-json でJSON形式の出力が可能
GitHub CLI: gh でIssueにコメントを投稿できる

制約・限界

claude-code-base-actionはGitHub Actions上での実行が前提で、ローカル実行履歴は対象外
ローカル実行履歴をGitHub Issueに自動投稿する確立された事例は発見できず
この分野はまだ未開拓領域と判断される

解決策（仮説）

提案するワークフロー

以下のシンプルなアプローチで課題解決を図る：

Issue作成: GitHub上で作業内容のIssueを事前に作成

Claude Code実行: headless modeでClaude Codeに明示的指示

claude -p "Issue #123を見て実装しろ。作業過程と判断理由をそのIssueにコメントとして投稿しろ" --output-format stream-json

自動記録: Claude CodeがGitHub CLIを使ってIssue commentに作業履歴を投稿
PR作成: 実装完了後、PRも作成

この方法の利点

シンプル: 既存機能のみで実現可能、複雑な追加開発不要
トレーサブル: Issue上に「なぜこの実装をしたのか」が記録される

想定される技術要素

Claude Code headless mode (--output-format stream-json)
GitHub CLI (gh issue comment)
Issue事前作成によるコンテキスト提供

次のステップ

検証予定項目

Claude CodeがGitHub CLI経由でIssue commentを投稿できるかの確認
headless modeでの指示内容の最適化
作業過程記録の品質評価

期待される効果

PRレビュー時の文脈理解向上
コードメンテナンス時の背景情報活用
Claude Code利用時のトレーサビリティ確保
チーム開発における透明性向上

すべての許可プロンプトを一括でスキップ

大変効率的ですが、大変危険なので利用は自己責任でお願いいたします。

claude --dangerously-skip-permissions

CLIのオプション一覧

公式ドキュメントはこちら

https://docs.anthropic.com/ja/docs/claude-code/cli-usage

nwiizo=sanの設定例

大変参考になるので見るべし

https://gist.github.com/nwiizo/8b7eb992875fc67a89368062d42d501e

トークン数を挙げるためのワード

https://simonwillison.net/2025/Apr/19/claude-code-best-practices/

下記でよりしっかり考えさせることができる（こともある）とのうわさ。

ultrathink

日本語だと

熟考
深く考えて
しっかり考えて

なのだとか。

https://x.com/millionbiz_/status/1929591134080454665

powershellでモデル一覧を表示

curl.exe "https://api.anthropic.com/v1/models" `
    -H "x-api-key: $Env:ANTHROPIC_API_KEY" `
    -H "anthropic-version: 2023-06-01"

AI連携エディタ利用を安全にする専用ユーザー作成のすすめ(Windows11)

2025-05-18

AI連携エディタは開発作業を効率化できる便利なツールですが、機密情報をうっかり渡してしまわないよう注意する必要があります。AI連携エディタが利用したデータは外部のAIサービスへ送信されているためです。「AI連携機能を利用する」＝「外部に情報を送信する」なのです。

機密性の低い情報に対してまで必要以上に警戒すべきとは言えません。それによって効率性を損なうことは別の問題を生じます。また現実問題として外部送信程度なら許容できるケースも多くあることでしょう。しかしAPIキーや顧客の個人情報などの機密性が極めて高い情報については話が別です。このような情報は送信してしまうだけで問題、まして悪用されたとなれば大問題です。ちゃんと外部AIに学習させない設定を有効化していれば外部AIに送った情報は流用されないはずですが、完璧とは限りません。AI連携エディタのCursorの開発元自身、シビアな用途で利用する際は注意するよう呼びかけています。

While we have several large organizations already trusting Cursor, please note that we are still in the journey of growing our product and improving our security posture. If you’re working in a highly sensitive environment, you should be careful when using Cursor (or any other AI tool).
(ref: https://www.cursor.com/ja/security)

エディタ内からAIに問い合わせなければ大丈夫とも言いきれません。AI連携エディタはバックグラウンドでもAIを利用しており、気付かないうちに情報が送信されうるためです。むしろ機密情報の書かれた設定ファイルを開くだけでもリスキーと考えるべきです。つまるところ、極めて厳しいセキュリティが必要とされる情報を取り扱っているなら、それらにアクセス自体できないようAI連携エディタを物理的あるいは論理的にシャットアウトするのが一番です。

専用ユーザーを作ろう

Windows11の場合、AI連携エディタを利用して開発を行うための専用ユーザーを作成することで、外部に送信される可能性のある情報をしっかり管理できます。この専用ユーザーにはあらかじめ公開可能なプロジェクトのみを渡し、機密情報が保存されたディレクトリにアクセスできないようにしておきます。うっかりミスで機密情報をAI連携エディタに渡してしまう事態を

Powershellで実施する場合はこのようなコードになります。

# AI連携エディタ用ユーザーの作成
# 
# [Usage]
# 1. 管理者権限で PowerShell を開きます。
# 2. スクリプトを一時的に実行できるようにします。(e.g. `Set-ExecutionPolicy RemoteSigned -Scope Process`)
# 3. スクリプトを保存したディレクトリに移動し、実行します。 (e.g. `.\create-ai-user.ps1 -Username AIUser -Password pass_is_here`)

param (
    [Parameter(Mandatory = $true)]
    [string]$Username,

    [Parameter(Mandatory = $true)]
    [string]$Password
)

$SecurePassword = ConvertTo-SecureString $Password -AsPlainText -Force
New-LocalUser -Name $Username -Password $SecurePassword -FullName "$Username" -Description "AI editor user (developer)"
if (-not $Username) {
    Write-Error "Fail to create user: $Username"
    exit 1
}

Add-LocalGroupMember -Group "Users" -Member $Username

管理者ユーザーではなくローカルユーザーとして作成します。その上で機密情報を取り扱うディレクトリやファイルのアクセス権を拒否し、アクセス自体不可能にします。