【Fedora 39】Claude CodeをJava開発（Maven/MariaDB）に導入する：安全な構築とAIとの共存ルール

【Fedora 39】Claude CodeをJava開発（Maven/MariaDB）に導入する：安全な構築とAIとの共存ルール その他（技術）

はじめに

自宅サーバー（Fedora 39）で運用しているJava 17 + MariaDBのログインシステムに、AI開発エージェント「Claude Code」を導入することを検討しました。AIにコードを任せる際の不安（ディレクトリ構造の維持や変更箇所の把握）を解消し、安全に開発を進めるためのベストプラクティスをまとめます。

① Claude Codeのインストール：rootか一般ユーザーか？

結論から言えば、「一般ユーザーアカウント」でのインストールが鉄則です。

  • 理由: rootでインストールすると、AIが作成するファイルもroot所有になり、Webサーバー（Apache等）やIDEから編集できなくなる「権限トラブル」を招くためです。

  • 推奨手順: nvm 等のバージョン管理ツールを使い、ユーザー権限の範囲内で
    npm install -g @anthropic-ai/claude-code
    を実行します。

② Maven構造と「三種の神器」によるコンテキスト管理

Claude Codeは標準的なMaven構造（src/main/javaなど）を理解しますが、より正確に動かすためには、以下のMarkdown（.md）ファイルをプロジェクト直下に配置するのが有効です。

.md ファイル（Markdown）とは何か？

一言で言えば、「人間が読みやすく、コンピュータ（AI）も解析しやすい」 テキストファイルです。

  • 見た目の特徴: # で見出し、* で箇条書き、``` で囲むとプログラムコードとして表示されます。

  • 働き: AI に対して「このプロジェクトのルールはこれだ」「今はここを直してほしい」という文脈（コンテキスト）を伝えるために使います。

    • spec.md（仕様書）: 何を作るか（例：ログイン認証のルール）。ログイン機能には ID/PASS が必要、XML はこの形式で出す、といった「ゴール」を定義します。
      # ログインシステム仕様
      * ユーザーIDとパスワードで認証を行う。
      * パスワードはハッシュ化して MariaDB に保存する。
      * 認証成功時は `/var/www/html/success.php` へリダイレクトする。

    • design.md（設計書）: どう作るか（例：MariaDBのテーブル構成、XMLの構造）。MariaDB のテーブル構成や、Java のパッケージ構成、利用するライブラリを定義します。
      # システム設計
      * **DB:** MariaDB (Table: users)
      * **Language:** Java 17 / Maven
      * **Config:** 接続情報は `src/main/resources/config.xml` に記述する。

    • plan.md（計画書）: 次に何をやるか（進捗管理）。「1. DB接続確認」「2. ログイン画面作成」など、作業の進捗を管理します。

    これらを用意することで、AIが「勝手に独自ルールで書き換える」のを防ぎ、文脈を維持した開発が可能になります。

    どのように使う（運用する）べきか？

    Claude Code を起動した状態で、以下のように指示を出します。

    「design.md と spec.md を読んで、不足している Java クラスを作成して。作業が終わったら plan.md の進捗を更新して」

    このように指示すると、Claude はバラバラな記憶ではなく、あなたが用意した .md ファイルという「正解」 に基づいて動いてくれます。

    メリット

    • ブレない: AI が勝手に「適当なライブラリ」を導入するのを防げます（design.md に書いてあるため）。

    • 再開が楽: 翌日に開発を再開する際、AI に「plan.md を読んで続きを教えて」と言えば、どこまでやったかをすぐに思い出してくれます。

    • Gitとの相性が抜群: これらの .md ファイルも Git で管理すれば、「いつ仕様（spec.md）が変わったか」をコードの修正履歴と一緒に残せます。

    ③ 最重要：AI専用設定ファイル「CLAUDE.md」

    人間用のメモ以上に重要なのが、Claude Codeが直接読み込む CLAUDE.md です。これをプロジェクトのルートに置くことで、AIは「自分の使い方」を理解します。

    CLAUDE.md の役割とメリット

    このファイルは、いわば 「AI専用のプロジェクト取扱説明書」 です。

    • 自動認識: Claude Code は起動時にこのファイルを探し、そこに書かれた「ビルドコマンド」や「テストコマンド」を学習します。

    • ルール遵守: Javaの命名規則や、あなたの環境特有の制約（MariaDBの接続先など）を書いておけば、AIが勝手にルールを破るのを防げます。

    • 効率化: 「テストして」と言うだけで、AIは CLAUDE.md を見て mvn test を実行し、エラーが出れば自分で修正案を考えます。

    【Fedora 39 / Java 向け設定例】

    Markdown

    # Claude Code Project Rules - Java Login System

## Build and Test Commands
- Build: `mvn clean compile`
- Test: `mvn test`
- Run: `mvn exec:java -Dexec.mainClass="com.example.Main"`
- Lint/Check: `mvn checkstyle:check`

## Code Style Patterns
- Language: Java 17
- Framework: Maven standard structure
- Naming: PascalCase for classes, camelCase for methods/variables
- Formatting: Follow Google Java Style (Indentation: 4 spaces)

## Project Context
- DB: MariaDB (MySQL compatible)
- Files: XML configuration is used for DB connection and login logic.
- Environment: Running on Fedora 39 Home Server.

## Development Constraints
- Use standard Maven directory layout (`src/main/java`, `src/main/resources`).
- Keep XML tags structured as defined in existing `.xml` files.
- Always run `mvn compile` after changing Java files to verify syntax.

    これがあることで、AIは自ら mvn test を叩き、エラーが出れば自律的に修正するようになります。

    この CLAUDE.md をプロジェクトのルートディレクトリ（一番上の階層）に配置します。

    my-login-system/ (プロジェクトのフォルダ)
├── CLAUDE.md           <-- ここに作成！
├── pom.xml
├── src/
└── (その他のファイル)

    ④ 変更箇所を「見える化」する唯一の方法：Git

    AIが「どこを書き換えたか」を理解し、最悪の事態（バグの混入）を防ぐための命綱が Git です。

    1. git init: プロジェクトをGit管理下におく。

    2. git diff: Claudeの作業後にこれを打つだけで、書き換わった行が赤と緑で表示される。

    3. git restore .: AIの変更が気に入らなければ、一瞬で元通りに。

    「Gitは難しい」と感じるかもしれませんが、「AI作業のバックアップ＆差分確認ツール」として割り切れば、3つほどのコマンドだけで運用可能です。

    ⑤ 実践に向けたロードマップ

    1. バックアップ: 現在のプロジェクトをコピーして保存。

    2. Git導入: git init と git commit で現状を記録。

    3. CLAUDE.md作成: ビルドコマンドを定義。

    4. 対話開始: Claude Codeを起動し、まずは小さな修正（コメントの追加など）から試す。

    おわりに

    AIは強力なパートナーですが、主導権は常に開発者にあります。Fedora環境とJavaの堅牢さを活かしつつ、Claude Codeという新しい風を取り入れることで、開発効率は劇的に向上するはずです。

※ 参考参照サイト
「Claude Code Template for Spring Boot」
「ジョインして3ヶ月のプロジェクトでClaude Code仕様駆動開発を試してみた」
「Launching a Claude Code Project: Design First, Then Build」

私の場合

自宅サーバーに　Node.js の環境ができているか否かを調べました。
①Node.js 本体の確認
node -v
node –version
上記で、「コマンドが見つかりません」となったので、下記でインストール
sudo dnf install nodejs
node –version
v20.17.0
②npm（パッケージ管理ツール）の確認
npm -v
10.8.2
③nvm（バージョン管理ツール）の確認
nvm –version
-bash: nvm: コマンドが見つかりません
となったので、nvm のインストールスクリプトを実行しました。
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
インストールが終わった直後は、まだ nvm コマンドが認識されないので、設定ファイルを読み込ませました。
source ~/.bashrc
その上で
nvm –version
0.39.7
現在 dnf で入っている Node.js とは別に、nvm 管理下の Node.js をインストールしました。
# 最新の長期サポート版 (LTS) をインストール
nvm install –lts
# インストールしたバージョンを使用する設定
nvm use –lts
Now using node v24.14.1 (npm v11.11.0)
既存の Node.js との使い分けについて（重要）
ここが少しややこしいのですが、現在のシステムには 2つの Node.js が共存している状態になります。
/usr/bin/node: dnf で入れたシステム標準版（root権限が必要な場合がある）
~/.nvm/versions/…: 今入れた nvm 版（こちらが優先されます）
Claude Code をインストールする際は、nvm 版が有効な状態で行う必要があります。
which node
~/.nvm/versions/node/v24.14.1/bin/node
実行結果が /home/testuser/.nvm/… のように、自分のホームフォルダ内を指していれば成功です！
Claude Code のインストール
nvm のおかげで、sudo を使わずにインストールできるようになっています。
npm install -g @anthropic-ai/claude-code
added 3 packages in 2s
2 packages are looking for funding
run `npm fund` for details
インストール成功。added 3 packages と表示されたのは、すでに必要な依存関係の多くがシステムやnvm環境に揃っていたため、非常にスムーズに完了した証拠です。
起動テスト
claude –version
2.1.91 (Claude Code)
バージョン番号が表示されたのでOK。プロジェクトフォルダに移動して、起動。
cd ~/my-app　# ログインシステムのフォルダへ移動
claude
※初回起動時には、Anthropicアカウントへのログイン（ブラウザが開くか、認証コードが表示される）を求められた。指示に従った。

Gitを「命綱」にする
Gitのインストール
sudo dnf install git -y
git –version
git version 2.47.0
インストールは成功。
git config –global user.name “testuser”
git config –global user.email “testuser@home.4423ch.com”

# 対話を始める前に打っておく
git init
git add .
git commit -m “Claude作業開始前のパックアップ”

これで、万一問題が起こっても、
git restore .
で、元に戻せます。

私は、CLAUDE.md を下記のように記載し、 ~/my-app に置いた。
cd ~/my-app
vi CLAUDE.md

# Claude Code Project Rules - Java Login System

## Build and Test Commands
- Build: `mvn clean compile`
- Test: `mvn test`
- Run: `mvn exec:java -Dexec.mainClass="com.example.Main"`
- Lint/Check: `mvn checkstyle:check`

## Code Style Patterns
- Language: Java 17
- Framework: Maven standard structure
- Naming: PascalCase for classes, camelCase for methods/variables
- Formatting: Follow Google Java Style (Indentation: 4 spaces)

## Project Context
- DB: MariaDB (MySQL compatible)
- Files: XML configuration is used for DB connection and login logic.
- Environment: Running on Fedora 39 Home Server.

## Development Constraints
- Use standard Maven directory layout (`src/main/java`, `src/main/resources`).
- Keep XML tags structured as defined in existing `.xml` files.
- Always run `mvn compile` after changing Java files to verify syntax.

[testuser@home my-app]$ claude
で、対話モードに入って、
「こんにちは。このプロジェクトは Java 17 と Maven を使ったログインシステムです。
pom.xml と CLAUDE.md を読んで、プロジェクトの構成を把握して。
MariaDB のテーブル定義や接続設定がどこにあるか、現在のソースから探して教えて。」
と話しかけました。

多くの情報が出てきました。私は下記のように言いました。

「今の回答、罫線記号を使わずに Markdown のテーブル形式で書き直して。あと、今後は ASCII アートや特殊な罫線を使わないでね。」

●O了解しました。今後はそのようにします。書き直します。

🚀 Claude Code によるプロジェクト解析結果

1. プロジェクト構成

フレームワーク・依存関係 (pom.xml)

  • Spring Boot 3.2.0 (Web + Data JPA)

  • MariaDB Java Client (JDBC ドライバ)

  • JUnit 3.8.1 (テスト用)

ソースファイル構成

| ファイルパス | 役割 |

| :— | :— |

| src/main/java/com/example/App.java | メインロジック（本体） |

| src/main/resources/application.properties | DB 接続設定 |

| src/test/java/com/example/AppTest.java | ユニットテスト |

2. MariaDB 接続設定 (application.properties)

項目 設定値
接続 URL jdbc:mariadb://localhost:3306/server_monitor
ユーザー dbuser
パスワード dbuserpass
ドライバ org.mariadb.jdbc.Driver
DDL 自動生成 update (起動時にテーブルを自動作成・更新)

3. テーブル定義 (JPA エンティティ)

users テーブル（ユーザー管理用）

| カラム名 | 型 | 備考 |

| :— | :— | :— |

| id | BIGINT | 主キー (AUTO_INCREMENT) |

| username | VARCHAR | ユーザー名 |

| password | VARCHAR | パスワード (平文保存) |

memos テーブル（家族伝言板用）

| カラム名 | 型 | 備考 |

| :— | :— | :— |

| id | BIGINT | 主キー (AUTO_INCREMENT) |

| username | VARCHAR | 投稿者名 |

| content | VARCHAR | メモ本文 |

| createdAt | TIMESTAMP | 作成日時 |

4. 実装機能一覧

エンドポイント 役割
GET / システムモニター表示 ＋ ログイン・メモ一覧
POST /login セッションベースのユーザー認証
GET /logout ログアウト処理
POST /register 新規ユーザー登録 (重複チェック機能付)
POST /post_memo 家族伝言板への新規投稿
GET /delete ユーザー削除 (admin 権限専用)

🛡️ 今後の改善ポイント (Claude の指摘)

  • セキュリティ: App.java:227 にてパスワードが平文で処理されています。Spring Security の BCrypt によるハッシュ化の導入が推奨されます。

  • 構成: 現在、テーブル定義は Java コード内の @Entity アノテーションに依存しています（Hibernate による自動生成）。

※今回はここまでとします。次回に続きます。

Views: 0

Post Views: 1