0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@rino_yume(rino yume)

WSLでpyenv + Codex CLI + Serena MCPを使う：Codex CLIと組み合わせてAIコーディングを効率化する

0
Posted at

WSLでpyenv + Codex CLI + Serena MCPを使う：Codex CLIと組み合わせてAIコーディングを効率化する

1. はじめに

ローカルコードをAIで修正するとき、単純にファイル全文を読ませるだけでは、プロジェクトが大きくなるほど効率が悪くなります。

そこで、WSL上に pyenv + Python 3.13 + uv + Serena MCP + Codex CLI を構成し、Serenaのシンボル解析を使って、関数・クラス・参照関係を見ながらコード修正できる環境を作ります。

この記事では、WSL上でSerena MCPを使うための導入方法と、効率よく作業するための運用ルールを簡潔にまとめます。

2. 想定環境

Windows 11
└─ WSL2 Ubuntu
   ├─ pyenv
   │  └─ Python 3.13.x
   ├─ uv
   ├─ Serena MCP
   ├─ Codex CLI
   └─ 作業プロジェクト

GUIアプリ、FastAPI、DuckDB、OpenLayersなどの複数ファイル構成のプロジェクトを、AIで安全に修正していく用途を想定します。

3. WSLに必要パッケージを入れる

sudo apt update
sudo apt install -y \
  git curl build-essential make gcc zlib1g-dev libssl-dev \
  libbz2-dev libreadline-dev libsqlite3-dev libffi-dev \
  liblzma-dev libncursesw5-dev xz-utils tk-dev \
  libxml2-dev libxmlsec1-dev ca-certificates

4. pyenvをインストールする

curl https://pyenv.run | bash

~/.bashrc に以下を追記します。

# pyenv
export PYENV_ROOT="$HOME/.pyenv"
[[ -d "$PYENV_ROOT/bin" ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - bash)"

反映します。

exec "$SHELL"
pyenv --version

5. Python 3.13を入れる

インストール可能なバージョンを確認します。

pyenv install --list | grep -E "^\s*3\.13\."

例として 3.13.5 を使う場合です。

pyenv install 3.13.5
pyenv global 3.13.5

python --version
which python

プロジェクトごとに固定する場合は、対象プロジェクト直下で以下を実行します。

cd ~/projects/MyProject_r001
pyenv local 3.13.5
python --version

6. uvをインストールする

Serenaはuv経由で導入するのが基本です。

curl -LsSf https://astral.sh/uv/install.sh | sh

uv が見つからない場合は、~/.bashrc に以下を追記します。

export PATH="$HOME/.local/bin:$PATH"

反映します。

exec "$SHELL"
uv --version

7. Serenaをインストールする

pyenvで有効になっているPythonを指定してSerenaを入れます。

uv tool install --python "$(pyenv which python)" serena-agent

serena --version
serena init

または、Python 3.13を直接指定する場合は以下でもよいです。

uv tool install -p 3.13 serena-agent
serena init

8. Codex CLIをインストールする

WSL側にCodex CLIを入れます。

curl -fsSL https://chatgpt.com/codex/install.sh | sh

確認します。

codex --version

9. CodexとSerena MCPを接続する

まず自動設定を試します。

serena setup codex

Codexを起動します。

codex

Codex内で以下を実行します。

/mcp

serena が表示されれば接続成功です。

10. 手動でMCP設定する場合

自動設定でうまくいかない場合は、WSL側の ~/.codex/config.toml を編集します。

mkdir -p ~/.codex
nano ~/.codex/config.toml

設定例です。

[mcp_servers.serena]
startup_timeout_sec = 30
tool_timeout_sec = 120
command = "serena"
args = [
  "start-mcp-server",
  "--project-from-cwd",
  "--context=codex",
  "--open-web-dashboard=false"
]

serena のパスを固定したい場合は確認します。

which serena

例:

/home/ユーザー名/.local/bin/serena

その場合は command にフルパスを指定します。

[mcp_servers.serena]
startup_timeout_sec = 30
tool_timeout_sec = 120
command = "/home/ユーザー名/.local/bin/serena"
args = [
  "start-mcp-server",
  "--project-from-cwd",
  "--context=codex",
  "--open-web-dashboard=false"
]

11. 作業プロジェクトをWSL側に置く

作業プロジェクトは /mnt/c/... よりも、WSLのLinuxファイルシステム側に置く方が快適です。

mkdir -p ~/projects
cd ~/projects
git clone <your-repository-url>
cd MyProject_r001

Windows側からコピーする場合は以下のようにします。

mkdir -p ~/projects/MyProject_r001
cp -r /mnt/c/WinPython/WPy64-313110/notebooks/MyProject_r001/* ~/projects/MyProject_r001/
cd ~/projects/MyProject_r001

12. Serenaプロジェクトを作成する

cd ~/projects/MyProject_r001

git init
git add .
git commit -m "initial import"

serena project create --index
serena project health-check

.serena/project.yml が作成されたら、重いファイルを除外します。

name: MyProject_r001

ignored_paths:
  - dist
  - build
  - __pycache__
  - .pytest_cache
  - .mypy_cache
  - data/raw
  - data/cache
  - "*.duckdb"
  - "*.tif"
  - "*.tiff"
  - "*.zip"
  - "*.exe"
  - "*.pyd"

initial_prompt: |
  このプロジェクトは WSL2 Ubuntu + pyenv + Python 3.13 で解析・修正します。
  Serena MCP を使って、関連クラス・関数・参照関係を確認してから修正してください。
  Pythonソースは UTF-8、Windows用 bat は Shift_JIS(cp932)+CRLF を維持してください。
  不要な仕様変更は避け、既存機能を維持してください。
  主要処理には日本語docstringと詳細コメントを追加してください。

13. AGENTS.mdを置く

Codexに毎回守ってほしいルールは、プロジェクト直下の AGENTS.md に書きます。

# AGENTS.md

## 環境

- このプロジェクトは WSL2 Ubuntu + pyenv + Python 3.13 で解析・修正する。
- Serena MCP を使って、関連クラス・関数・参照関係を確認してから修正する。
- Pythonソースは UTF-8。
- Windows用 `.bat` ファイルは Shift_JIS(cp932) + CRLF を維持する。
- GUIは PySide6 + pyqtgraph を優先する。
- Web地図は OpenLayers、APIは FastAPI、DBは DuckDB を基本とする。

## 作業ルール

- 不要な仕様変更は行わない。
- 既存のUI名、タブ名、ファイル構成を勝手に戻さない。
- 修正前にSerenaで関連シンボルを確認する。
- 大きなファイルは機能単位で分割する。
- 主要クラス、関数、処理ブロックには日本語docstringと詳細コメントを追加する。
- 修正後はgit diffを確認する。

## 実行確認

- WSL側では `python -m compileall src` を実行する。
- GUIの最終確認は、必要に応じてWindows側WinPythonで行う。
- FastAPIは `python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload` で確認する。

## 禁止事項

- 勝手にPythonバージョンを変更しない。
- `.bat` ファイルをUTF-8に変換しない。
- 依頼外の大規模リファクタリングをしない。

14. 起動用スクリプトを作る

start_codex_serena_wsl.sh を作成します。

nano start_codex_serena_wsl.sh

以下にstart_codex_serena_wsl.shの内容を示します。

#!/usr/bin/env bash
set -euo pipefail

# ============================================================
# Codex CLI + Serena MCP 起動スクリプト
# ------------------------------------------------------------
# WSL2 Ubuntu + pyenv + Python 3.13 を前提に、
# 対象プロジェクトでCodex CLIを起動します。
# ============================================================

PROJECT_DIR="$HOME/projects/MyProject_r001"
PYTHON_VERSION="3.13.5"

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$HOME/.local/bin:$PATH"
eval "$(pyenv init - bash)"

cd "$PROJECT_DIR"
pyenv local "$PYTHON_VERSION"

echo "=========================================="
echo "Codex + Serena + WSL pyenv"
echo "=========================================="
echo "Project: $PROJECT_DIR"
echo "Python : $(python --version)"
echo "Serena : $(serena --version || true)"
echo

codex -C "$PROJECT_DIR" -a on-request -s workspace-write

実行権限を付けます。

chmod +x start_codex_serena_wsl.sh
./start_codex_serena_wsl.sh

15. Codex起動後の最初のプロンプト

Codexが起動したら、最初に以下を入力します。

Activate the current dir as project using serena.

このプロジェクトをオンボーディングしてください。
WSL2 Ubuntu + pyenv + Python 3.13 前提で、構成、主要ファイル、起動方法、GUI、計算処理、描画処理、FastAPI/DuckDB構成、batファイルの扱いを把握してください。
まだコードは変更しないでください。

16. 効率よく作業するコツ

16.1. 最初は調査だけにする

まだコードは変更しないでください。
Serenaで関連シンボル、呼び出し関係、変更影響範囲を調べて、修正計画だけ出してください。

16.2. 1回の修正範囲を小さくする

- UI表示名だけ
- 描画更新だけ
- 計算ロジックだけ
- bat修正だけ
- 使用方法HTMLだけ
- README / Qiita記事だけ

16.3. 修正後は必ず差分確認する

git status
git diff
python -m compileall src

Codexには以下のように指示すると安全です。

修正後に git diff を確認し、変更ファイルごとに何を変えたか説明してください。

17. まとめ

WSLのpyenvでSerena MCPを使う基本形は以下です。

WSL Ubuntu
  ├─ pyenv install 3.13.x
  ├─ uv install
  ├─ uv tool install --python "$(pyenv which python)" serena-agent
  ├─ serena setup codex
  └─ codex -C ~/projects/MyProject_r001 -a on-request -s workspace-write

Serena MCPを使うことで、Codex CLIにシンボル検索・参照解析・構造理解を補助させることができます。

大きなPython GUIアプリや、FastAPI + DuckDB + OpenLayersのような複数ファイル構成のプロジェクトでは、特に効果があります。

18. 参考リンク

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?