devtu-github

DevTU GitHub ワークフロー

プッシュ前のクリーンアップ、pre-commit フック、テスト検証を徹底し、ToolUniverse のコードを安全に GitHub にプッシュします。

手順

ユーザーがコードのプッシュ、CI の修正、コミットの準備を希望した場合は、次のワークフローに従ってください。

フェーズ 1：プッシュ前のクリーンアップ

1. 一時ファイルをルートディレクトリの外に移動する - セッション文書やその場限りのテストスクリプトはプッシュしてはいけません。

# Move session markdown files to temp_docs_and_tests/
for f in $(ls *.md 2>/dev/null | grep -v README.md | grep -v CHANGELOG.md | grep -v LICENSE.md); do
  mv "$f" temp_docs_and_tests/
done

# Move root-level test scripts to temp_docs_and_tests/
for f in $(ls test_*.py 2>/dev/null); do
  mv "$f" temp_docs_and_tests/
done

2. 不要なファイルがステージングされていないことを確認する：

git status --short

要注意項目 - 次のファイルは絶対にステージングしてはいけません。

• ルートディレクトリにある *_SUMMARY.md、*_REPORT.md、SESSION_*.md
• ルートディレクトリにある test_*.py（正式なテストではなく、その場限りのスクリプトです）
• .env または認証情報ファイル
• temp_docs_and_tests/ の内容

フェーズ 2：pre-commit フックを有効化する

3. pre-commit がインストールされ、有効になっていることを確認する：

pre-commit install

これにより、git commit のたびに次のチェックが自動で実行されます。

• ruff check --fix - 自動修正付きの Python リント
• ruff format - コードのフォーマット
• YAML/TOML の検証
• 行末の空白の削除
• ファイル末尾の修正

4. フックが有効になっていることを確認する：

ls -la .git/hooks/pre-commit

フェーズ 3：テストを実行する

5. テストスイート全体をローカルで実行する：

python -m pytest tests/ -x --tb=short -q

6. テストが失敗した場合は、以下のエラーパターンを使って原因を特定し、続行する前に修正します。

フェーズ 4：コミットしてプッシュする

7. 特定のファイルだけをステージングする（git add . や git add -A は絶対に使用しないでください）：

git add src/tooluniverse/specific_file.py tests/specific_test.py

8. コミットする（pre-commit フックは自動で実行されます）：

git commit -m "Clear, descriptive message"

9. プッシュする前に、最新の main にリベースする（重要 — PR の競合を防ぎます）：

git fetch origin
git stash            # stash any uncommitted work
git rebase origin/main
git stash pop        # restore uncommitted work

リベースで競合が発生した場合は解決し（こちらの新しい変更を維持して）、次を実行します。

git add <conflicted-file>
git rebase --continue

10. プッシュする（リベース後は force-with-lease を使用します）：

git push --force-with-lease origin <branch-name>

プッシュ後、PR に競合がないことを確認します。

gh pr view <PR-number> --json mergeable,mergeStateStatus
# Must show: "mergeable":"MERGEABLE"

絶対にプッシュしてはいけないファイル

一時セッション文書（ルート階層の .md）

これらは開発中に作成されたセッションメモです。コミット前に temp_docs_and_tests/ に移動してください。

パターン	例
*_SUMMARY.md	API_DISCOVERY_SESSION_SUMMARY.md
*_REPORT.md	SKILL_TESTING_REPORT.md、TOOLUNIVERSE_BUG_REPORT.md
SESSION_*.md	SESSION_2026_02_13.md
IMPLEMENTATION_*.md	IMPLEMENTATION_COMPLETE.md
BUG_ANALYSIS_*.md	BUG_ANALYSIS_DETAILED.md
FIX_*.md	FIX_SUMMARY.md、CORRECT_FIX.md
AGENT_*.md	AGENT_DESIGN_UPDATES.md

例外：README.md、CHANGELOG.md、LICENSE.md は正式なドキュメントなので、必ず残してください。

ルート階層のテストスクリプト

ルートディレクトリにある test_*.py のような、その場限りのテストスクリプトはテストスイートの一部ではありません（テストスイートは tests/ ディレクトリにあります）。temp_docs_and_tests/ に移動してください。

ファイル	用途
test_clear_tools.py	1 回限りのツールクリーンアップテスト
test_finemapping_tools.py	その場限りのツール検証
test_metabolomics_tools.py	その場限りのツール検証
test_original_bug.py	バグの再現
test_pathway_tools.py	その場限りのツール検証
test_protein_interaction_skill.py	スキルのテスト
test_reload_fix.py	バグの再現
test_round10_tools.py	その場限りのツール検証

その他の除外ファイル

• .env - 秘密情報を含む環境変数
• temp_docs_and_tests/ - すでに .gitignore に登録されています
• .claude/ - Claude Code の設定
• __pycache__/、*.pyc - Python のバイトコード
• .DS_Store - macOS のメタデータ

よくあるテスト失敗パターン

パターン 1：KeyError: 'role'

症状：メッセージの dict にアクセスした際に KeyError: 'role' が発生します。

修正方法：tu.run() に return_message=True を追加し、.get() を使用します。

messages = tu.run(calls, use_cache=True, return_message=True)
if msg.get("role") == "tool":

パターン 2：Mock を添字で参照できない

症状：TypeError: 'Mock' object is not subscriptable が発生します。

修正方法：all_tool_dict には実際の dict を使用し、_get_tool_instance を追加します。

mock_tu.all_tool_dict = {"Tool": mock_tool}
mock_tu._get_tool_instance = lambda name, cache=True: mock_tu.all_tool_dict.get(name)

パターン 3：リントエラー（F841、E731）

F841 の修正方法（未使用の変数）：_ プレフィックスを使用するか、_ = func() とします。 E731 の修正方法（ラムダの代入）：def に置き換えます。

パターン 4：Git で追跡されている一時ファイル

症状：git status に一時ファイルが変更済みまたはステージング済みとして表示されます。

修正方法：

git rm -r --cached temp_docs_and_tests/
git rm --cached API_DISCOVERY_SESSION_SUMMARY.md
git commit -m "Remove temp files from tracking"

Pre-Commit フックの設定

このプロジェクトでは .pre-commit-config.yaml を使用します。

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    hooks: [end-of-file-fixer, trailing-whitespace, check-yaml, check-toml]
  - repo: https://github.com/astral-sh/ruff-pre-commit
    hooks: [ruff-check --fix, ruff-format]

対象範囲：^(ToolUniverse/)?src/tooluniverse/ に一致するファイルのみ

クイックリファレンス

タスク	コマンド
フックを有効化する	pre-commit install
すべてのテストを実行する	pytest tests/ -x --tb=short -q
特定のテストを実行する	pytest tests/path/test.py::Class::method -xvs
ステージ済みファイルを確認する	git status --short
ファイルをステージング解除する	git restore --staged <file>
追跡対象から削除する	git rm --cached <file>
一時ファイルを移動する	フェーズ 1 のコマンドを参照
フックを手動で実行する	pre-commit run --all-files

プッシュ前チェックリスト

プッシュする前に、以下を確認してください。

• 一時的な Markdown ファイルをルートから temp_docs_and_tests/ に移動した
• ルートレベルの test_*.py スクリプトを temp_docs_and_tests/ に移動した
• Pre-commit フックをインストールした（pre-commit install）
• すべてのテストがローカルで成功する（pytest tests/ -x）
• リントエラーがない
• 関連するファイルのみがステージされている（.env や一時ファイルが含まれていない）
• コミットメッセージが明確で説明的である
• 正しいブランチが選択されている

Git コミットのガイドライン

• コミットに AI による帰属情報を含めないでください
• セッションのドキュメントである Markdown ファイルをコミットしないでください
• git add . ではなく git add <specific-files> を使用してください
• 明快でプロフェッショナルなコミットメッセージを書いてください
• 1 つのコミットにつき、論理的な変更を 1 つにしてください