GitHub Development Standard Skill

プロセス > モデルの能力。低性能モデルは問題ではない。プロセスがないことが問題だ。

本Skillは Claude Sonnet 4.6 が実際のAI生成プロジェクト（lobster-press / openclaw-portable / smart-search-fusion）のコード審査経験に基づいて最適化したもので、AI補助開発の頻出する落とし穴に対する専門的な対応を追加しています。

---

🎯 対象者

• 低性能/中程度のAIモデル（GLM-4-Flash、GLM-4など）：本規範を使用して生成動作を制約する
• 初心者プログラマー：本規範を使用して正しいエンジニアリング直感を構築する
• あらゆるAI補助開発シナリオ：「生成したらすぐコミット」による品質の崩壊を防止する

---

💡 コアコンセプト

問題を定義する → 修正方法を定義する → コードを書く → 検証する → 最後に公開する

ステップをスキップしてはいけない。 ステップをスキップするたびに、将来の自分に地雷を埋めることになります。

---

🚨 AI生成プロジェクトの頻出する落とし穴（新規追加）

これが本規範の重要な追加部分です。これらの落とし穴は実際のAI生成プロジェクトのコード審査から導き出されています。

落とし穴1：同じ日に複数のバージョンをリリース（最も致命的）

症状：

v3.0.0  2026-03-17
v2.6.0  2026-03-17
v2.5.0  2026-03-17
v2.0.0  2026-03-15

問題： バージョン履歴は事後に作成されたもので、実際の進化ではありません。経験のある開発者がこれを見たら、すぐに信頼を失います。

ルール： バージョン番号は時間に裏付けられるべきで、テキストの説明で決まるものではありません。1つのcommitが1つの実際の変更に対応し、事後に歴史を作り上げてはいけません。

正しいやり方：

# 今日から、各変更 → 1つの実際のcommit → 必要な時だけtagを付ける
git add .
git commit -m "fix: XXX の問題を修正"
# リリース準備ができた時だけ tag を付ける
git tag v1.0.0
git push origin v1.0.0

---

落とし穴2：Gitのマージ競合マーカーがメインブランチにコミットされる

症状： README.md の末尾に以下が表示される：

<<<<<<< HEAD
![Star History Chart](...)
=======
[![GitHub stars](...)
>>>>>>> 896d1b6

問題： ユーザーが見るREADMEは破損しています。これは「生成後にすぐコミット、人的レビューなし」の直接的な結果です。

各commitの前に必ず実施する30秒チェック：

# すべてのMarkdownファイルに競合マーカーがないか確認
grep -r "<<<<<<\|>>>>>>\|=======" *.md **/*.md 2>/dev/null \
  && echo "❌ マージ競合が検出されました。先に解決してください" || echo "✅ 競合マーカーなし"

---

落とし穴3：ルートディレクトリのドキュメント爆発

症状：

RELEASE_SUCCESS.md
PUSH_TO_GITHUB.md
DUAL_RELEASE_SUMMARY.md
STAR_HISTORY_FIX.md
RELEASE_NOTES_v5.0.2.md
RELEASE_NOTES_v5.0.3.md
README_V5.md

問題： AIは毎回生成するたびに、既存ファイルを修正するのではなく新しいファイルを作成する傾向があり、ルートディレクトリが一度きりの一時的なドキュメントで埋め尽くされます。

ルートディレクトリにあるべき内容：

README.md          # メインドキュメント（必須）
LICENSE            # ライセンス（必須）
CHANGELOG.md       # バージョン履歴（唯一）
CONTRIBUTING.md    # 貢献ガイド（オプション）
+ 必要な設定ファイル（package.json / pyproject.toml など）

クリーンアップコマンド：

# どのファイルを削除すべきか確認
ls -1 | grep -E "RELEASE_NOTES_v|RELEASE_SUCCESS|PUSH_TO_GITHUB|DUAL_RELEASE|STAR_HISTORY|README_V[0-9]"

# 価値のあるコンテンツをまず CHANGELOG.md にマージしてから削除
git rm RELEASE_SUCCESS.md PUSH_TO_GITHUB.md  # など
git commit -m "chore: ルートディレクトリの冗長なドキュメントを削除"

---

落とし穴4：README内のリンクのバージョン番号が一致していない

症状：

📥 **Download**: [OpenClaw-v6.0.0-windows.tar.gz](
  https://github.com/xxx/releases/tag/v5.1.0)

テキストはv6.0と言っているのに、リンクはv5.1を指しています。

確認コマンド：

# README内のすべてのリリースリンクからバージョン番号を抽出し、一致しているか確認
grep -oE "releases/tag/v[0-9]+\.[0-9]+(\.[0-9]+)?" README*.md | sort | uniq -c
# 複数の異なるバージョン番号が出現 → 修正が必要

---

落とし穴5：反証不可能な「初」「世界初」の主張

症状：

"The World's First Truly Offline AI Assistant"
"Ebbinghaus忘却曲線をLLMメモリ管理に初めて適用"

問題： AIの学習データは論文の要約で満ちており、「first/novel」という表現に満ちています。モデルはこのような表現を容易に生成してしまいます。しかし、引用の裏付けのない主張は、専門的なユーザーに直ちに信頼を失わせます。

ルール：

• 文献で裏付けられている → 記述可能、引用を添付する
• 裏付けがない → 説明的な表現に変更し、何をしたかを述べるが、「初」であることは言わない

---

落とし穴6：設定ファイルパスのドキュメントとコードの不一致

症状： ドキュメントでは config/config.json に設定を配置するよう指示していますが、コードの実際の読み込みは scripts/config.json です。ユーザーがドキュメント通りに操作すると、機能が動作しません。

確認コマンド：

# コード内で設定ファイルを読み込むパスをすべて検出
grep -rn "config\.json\|config_file\|CONFIG_FILE" scripts/ src/ *.py *.sh 2>/dev/null

# README で記述されている設定パスと比較
grep -n "config" README.md | grep -i "copy\|edit\|path\|配置"

---

📋 9ステップの開発プロセス

1. Issue を読む → 2. タスクカードを書く → 3. 基準バージョンを確定
     ↓
4. 変更点をリストアップ → 5. コーディング → 6. ローカル検証
     ↓
7. diff を確認 → 8. リリース説明を書く → 9. ふりかえり

Step 1：Issue を読む（理解するのみ、コード変更なし）

• ✅ 問題の現象と期待される動作を理解する
• ❌ 記憶で推測してはいけない
• ❌ 急いでコードを見てはいけない

Step 2：「5行タスクカード」を書く

【タスク種別】バグ修正 / 機能追加 / ドキュメント修正
【目標】1文での説明
【境界】どのファイル/関数のみを修正するか
【対象外】変更しないコンテンツを明確に
【影響範囲】影響を受けるモジュール/機能

Step 3：基準バージョンを確定

git tag | sort -V | tail -5
git checkout v1.2.4

Step 4：変更点をリストアップ

【変更点1】
場所：src/xxx.py 第XX行
変更前：<古いコード>
変更後：<新しいコード>
理由：<なぜこのように変更するのか>

Step 5：コーディング（Karpathy の4大原則 + 8つの規律）

Karpathy の4大原則（Andrej Karpathy のLLMプログラミング観察に由来）

原則1：考えてから動く（Think Before Coding）

推測するな。困惑を隠すな。トレードオフを積極的に露出させよ。

• 不確かな時は、まず仮定を述べ、推測で進めない
• 複数の理解がある場合、すべての選択肢をリストアップし、こっそり1つを選ばない
• より単純な方案が存在する場合、積極的に提案する
• 不明確な場合は、無理に進めずに停止して質問する

原則2：シンプルさを最優先に（Simplicity First）

最小限のコードで問題を解く。推測的なものは作らない。

• 要求されていない機能を追加しない
• 一度限りのコードを抽象化しない
• 要求されていない「柔軟性」や「設定可能性」を追加しない
• 起こりえない状況のエラー処理を書かない
• 200行で解決できることを50行以上で書かない（50行で十分なら書き直す）

検証基準：経験豊かなエンジニアが「過度な設計」と言うだろうか？そうなら、単純化する。

原則3：手術的な変更（Surgical Changes）

必ず変更すべきことだけを変更する。自分が汚したことだけを片付ける。

• 「ついでに」隣接するコード、コメント、フォーマットを変更しない
• 壊れていないものを重構築しない
• すでに存在するスタイルに合わせ、自分のやり方が違うとしても
• 無関係なデッドコードを見つけたら指摘する。ただ、削除はしない
• 自分の変更により生じた廃棄된import/変数/関数は必ず削除する
• 他人が残したデッドコードを削除しない。要求されない限り

検証基準：各行の変更がユーザーの要求に追跡可能であるべき。

原則4：目標駆動の実行（Goal-Driven Execution）

成功基準を定義する。検証を循環して通過するまで繰り返す。

曖昧なタスクを検証可能な目標に変換する：

• 「検証を追加」→ 「失敗するテストケースを先に書き、その後通す」
• 「バグを修正」→ 「再現するテストを先に書き、その後通す」
• 「X をリファクタ」→ 「リファクタ前後でテストが通る」

複数ステップのタスクではプランをリストアップする：

1. [ステップ] → 検証: [チェックポイント]
2. [ステップ] → 検証: [チェックポイント]
3. [ステップ] → 検証: [チェックポイント]

8つのコーディング規律（必須）

1. 古いコードをまずコピーし、その後局所的に置換する。記憶で書き直さない
2. 関数を変更する前に、関数の入力、出力、副作用を通読する
3. データ構造の変更が必要な場合、すべての使用箇所を先に検索する
4. ロジックとスタイルを同時に変更しない
5. バグ修正の中でリファクタリングしない
6. 要求されていない動作を変更しない
7. 検証なしに「修正した」と言わない
8. リリースノートが実際のコードを上回らないようにする

Step 6：ローカル検証（4層テスト）

# Layer 1: 構文検証（1秒）
python3 -m py_compile src/xxx.py
# シェルスクリプト構文チェック
bash -n scripts/xxx.sh && echo "✅ 構文OK"

# Layer 2: インポート検証（1秒）
python3 -c "from src.xxx import ClassName; print('ok')"

# Layer 3: 動作検証（5-30分）
python3 -m pytest tests/unit/ -v

# Layer 4: 回帰検証（5-30分）
python3 -m pytest tests/ -v

Step 7：diff を確認（3つの事項をチェック）

タスク種別	予想される変更行数
1つの小さいバグ修正	5–30行
関連する複数のバグ修正	20–80行
小さい機能追加	30–150行
200行超え	変更が多すぎないか疑う

確認：変更行数はタスク規模に合致しているか → 対象外エリアまで変更していないか → リリース説明がdiffと一致しているか

Step 8：リリース説明を書く

fix: XXX の問題を修正

問題：
- 問題の説明

修正：
- 修正方法

検証：
- ✅ 構文チェック通過
- ✅ インポートチェック通過
- ✅ 動作検証通過
- ✅ 回帰テスト通過

影響範囲：
- 修正されたファイル/関数

非修正：
- XXX は修正していません

Closes #XX

Step 9：ふりかえり

良かった点：...
改善できる点：...
学んだ経験：...

---

✅ 15項目の受け入れ基準リスト + 6項目のAI専項チェック

リリース前に、各項目に答える。1つでも答えられない項目があれば、リリースしない。

A. 要件一致性（3項目）

• A1. この修正の目標を1文で説明できる
• A2. この修正で「変更しない」コンテンツを知っている
• A3. コード変更はissueの説明と一致している

B. 技術的正確性（4項目）

• B1. 正しいバージョンから修正を開始した
• B2. ファイル全体を書き直していない
• B3. データ構造の変更がすべての参照箇所に同期されている
• B4. 新しいロジックが古いロジックを破壊していない

C. テスト検証（4項目）

• C1. 構文チェック通過
• C2. インポートチェック通過
• C3. 最小限のサンプル検証通過
• C4. 回帰テスト通過

D. リリース品質（4項目）

• D1. diff のサイズがタスク規模に合致している
• D2. リリースノートが実際のコードと一致している
• D3. バージョン番号、ドキュメント、コメントが同期されている
• D4. この変更のリスク箇所を指摘できる

E. AI生成専項チェック（6項目）⭐ 新規追加

• E1. README に <<<<<<< / >>>>>>> の競合マーカーがない
• E2. ルートディレクトリに一時的なドキュメント（RELEASE_SUCCESS / PUSH_TO_GITHUB など）がない
• E3. すべてのダウンロードリンクのバージョン番号が現在のリリースと一致している
• E4. バージョン履歴に同じ日に3つ以上のバージョンがない
• E5. README に反証不可能な「初」「世界初」の主張がない
• E6. ドキュメントで説明されている設定パスとコードの実際の読み込みパスが一致している

---

🛠️ ワンクリック自己チェックスクリプト（新規追加）

commitの前に一度実行してください：

#!/bin/bash
# pre-commit-check.sh — AI補助プロジェクトの送信前自己チェック
# 使用方法: bash pre-commit-check.sh
# gitフックとしてインストール: cp pre-commit-check.sh .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

echo "=== 🔍 送信前自己チェック ==="
PASS=true

# E1: マージ競合マーカーをチェック
if grep -rq "<<<<<<\|>>>>>>" *.md 2>/dev/null; then
  echo "❌ [E1] マージ競合マーカーが検出されました。先に解決してください"
  PASS=false
else
  echo "✅ [E1] マージ競合マーカーなし"
fi

# E2: ルートディレクトリの冗余なドキュメントをチェック
JUNK=$(ls -1 | grep -E "RELEASE_SUCCESS|PUSH_TO_GITHUB|DUAL_RELEASE|STAR_HISTORY_FIX|README_V[0-9]")
if [ -n "$JUNK" ]; then
  echo "❌ [E2] 冗余なドキュメントが検出されました:"
  echo "$JUNK" | sed 's/^/   /'
  PASS=false
else
  echo "✅ [E2] ルートディレクトリはクリーン"
fi

# E3: ダウンロードリンクのバージョン番号の一貫性をチェック
VERSIONS=$(grep -ohE "releases/tag/v[0-9]+\.[0-9]+(\.[0-9]+)?" README*.md 2>/dev/null | grep -oE "v[0-9]+\.[0-9]+(\.[0-9]+)?" | sort -u)
COUNT=$(echo "$VERSIONS" | grep -c "v" 2>/dev/null || echo 0)
if [ "$COUNT" -gt 1 ]; then
  echo "❌ [E3] README に複数の異なるバージョンのダウンロードリンクが存在します:"
  echo "$VERSIONS" | sed 's/^/   /'
  PASS=false
else
  echo "✅ [E3] ダウンロードリンクのバージョン番号は一致"
fi

# C1: Python構文チェック
PY_FILES=$(find . -name "*.py" -not -path "./.git/*" 2>/dev/null)
if [ -n "$PY_FILES" ]; then
  PY_ERR=false
  while IFS= read -r f; do
    python3 -m py_compile "$f" 2>/dev/null || { echo "❌ [C1] Python構文エラー: $f"; PY_ERR=true; PASS=false; }
  done <<< "$PY_FILES"
  [ "$PY_ERR" = false ] && echo "✅ [C1] Python構文すべて通過"
fi

# C1: シェル構文チェック
SH_FILES=$(find scripts/ -name "*.sh" 2>/dev/null)
if [ -n "$SH_FILES" ]; then
  SH_ERR=false
  while IFS= read -r f; do
    bash -n "$f" 2>/dev/null || { echo "❌ [C1] シェル構文エラー: $f"; SH_ERR=true; PASS=false; }
  done <<< "$SH_FILES"
  [ "$SH_ERR" = false ] && echo "✅ [C1] シェル構文すべて通過"
fi

echo ""
if [ "$PASS" = true ]; then
  echo "✅ すべてのチェックに通過。commitできます"
  exit 0
else
  echo "❌ 問題があります。修正してからcommitしてください"
  exit 1
fi

---

🔧 GitHub CLI クイックリファレンス

# Issue を表示
gh issue view 53 --repo owner/repo

# Issue にコメントして閉じる
gh issue comment 53 --repo owner/repo --body "修正説明..."
gh issue close 53 --repo owner/repo

# PR のステータスとCI を表示
gh pr view 55 --repo owner/repo
gh pr checks 55 --repo owner/repo

# PR をマージ
gh pr merge 55 --squash --repo owner/repo

---

📊 効果比較

指標	規範なし	規範あり
バグ修正の返工率	60%	5%
平均変更行数	200+ 行	15 行
無関係な機能混入率	70%	0%
マージ競合の残留	よくある	0%
ルートディレクトリの冗余ドキュメント	よくある	0%
ダウンロードリンクエラー	たまに	0%

---

📚 参考資料

• docs/workflow.md — 9ステップのプロセス詳細
• docs/validation.md — 4層検証の詳細
• docs/checklist.md — 15項目リスト（印刷版）
• examples/lobster-press-bugfix.md — 実際の修正事例
• templates/任務卡片模板.md — タスクカードテンプレート

---

🙏 謝辞

• オリジナル版: SonicBotMan Team（実際のスタートアップチームの落とし穴経験に基づく）
• v2.0 最適化: Claude Sonnet 4.6（lobster-press / openclaw-portable / smart-search-fusion の実際のコード審査に基づく）
• 方法論の出所: ソフトウェアエンジニアリングのベストプラクティス + AI補助開発の実体験

---

コードの品質で妥協しない。プロセスを信頼しろ。「修正した」を信頼するな。 💪