review-ai-writing

AI による文章生成パターンのレビュー

エージェントが対応している場合は成果物のグループごとに並列処理し、開発者向けのテキスト成果物全体から AI 生成文章のパターンを検出します。

使用方法

オプションのフラグを指定して review-ai-writing スキルを呼び出します：review-ai-writing [--all] [--category <name>] [path]。

フラグ：

• --all - コードベース全体をスキャンします（デフォルト：main からの変更ファイル）
• --category <name> - 特定のカテゴリのみをチェックします：content|vocabulary|formatting|communication|filler|code_docs
• パス：対象ディレクトリ（デフォルト：現在の作業ディレクトリ）

手順

1. 引数を解析する

$ARGUMENTS からフラグを抽出します：

• --all - コードベース全体をスキャンします
• --category <name> - 特定のカテゴリに絞り込みます
• パス - 対象ディレクトリ

2. スキルを読み込む

検出結果を報告する前に、review-verification-protocol スキルを読み込みます。AI による文章生成パターンのカタログは、このファイルの「Reference Material」セクションと references/*.md ファイルにあります。チェックするカテゴリを読み込んでください。

3. 対象範囲を決定する

# Default: changed files from main
git diff --name-only $(git merge-base HEAD main)..HEAD

# If --all flag: scan all text artifacts
find . -type f \( -name "*.md" -o -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" -o -name "*.swift" -o -name "*.kt" -o -name "*.ex" -o -name "*.exs" \) ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/vendor/*" ! -path "*/__pycache__/*" ! -path "*/dist/*" ! -path "*/build/*"

ファイルが見つからない場合は、次のメッセージを表示して終了します："No files to scan. Check your branch has changes or use --all."

4. 既存の LLM 成果物レビューを確認する

# Check if llm-artifacts review exists to avoid double-flagging
if [ -f .beagle/llm-artifacts-review.json ]; then
  echo "Found existing llm-artifacts review — will skip overlapping findings"
fi

.beagle/llm-artifacts-review.json が存在する場合は、既存の検出結果を解析します。統合する際は、ファイルと行、およびパターンタイプの両方が既存の llm-artifacts の検出結果と一致する項目をスキップします（特に verbose_comment と over_documentation のタイプ）。

5. ファイルを種類別に分類する

ファイルを次の3つのグループに分類します：

グループ	ファイルの種類	チェックするパターン
文章	*.md	6つすべてのカテゴリ
コードドキュメント	*.py, *.ts, *.tsx, *.js, *.jsx, *.go, *.rs, *.java, *.rb, *.swift, *.kt, *.ex, *.exs	vocabulary, communication, filler, code_docs
Git	コミットメッセージ、PR の説明	content, vocabulary, communication, filler

Git の成果物については、最近のコミットを収集します：

# Commits on current branch not in main
git log --format="%H %s" $(git merge-base HEAD main)..HEAD

6. 各成果物グループをスキャンする

以下に3つの成果物グループ（文章、コードドキュメント、Git）を示します。エージェントがサブエージェントに対応していて、項目の合計が4つ以上の場合は、対象範囲内の各グループに1つずつサブエージェントを割り当て、並列で処理します（最大3つ）。それ以外の場合は、同じグループの手順を自分で順番に実行します。いずれの場合も出力は同一です。--category が指定されている場合は、一致するカテゴリのみを処理します。各サブエージェント（または順次実行する各処理）は、スキャン前にこのスキルの「Reference Material」と関連する references/*.md のパターンを読み込みます。

グループ 1：文章

対象範囲： Markdown ファイルのみ
チェック： 6つすべてのパターンカテゴリ
手順：

1. 各 Markdown ファイルを読み込みます
2. すべてのパターンカテゴリをスキャンします
3. このスキルに記載されている誤検出チェックを適用します
4. 構造化された形式で検出結果を返します

グループ 2：コードドキュメント

対象範囲： ソースコードファイル
チェック： vocabulary、communication、filler、code_docs カテゴリ
手順：

1. 各ファイルから docstring とコメントを抽出します
2. 該当するパターンカテゴリをスキャンします
3. コード自体はスキップし、コメントと docstring 内のテキストのみをチェックします
4. 構造化された形式で検出結果を返します

グループ 3：Git

対象範囲： コミットメッセージと PR の説明
チェック： content、vocabulary、communication、filler カテゴリ
手順：

1. ブランチのコミットメッセージを読み込みます
2. PR ブランチ上にいる場合は、gh pr view --json body を使用して PR の説明を読み込みます
3. 該当するパターンカテゴリをスキャンします
4. 合成パスを使用します：git:commit:<sha> は行 0、git:pr:<number> は行 0
5. 構造化された形式で検出結果を返します

7. 検出結果を統合する

すべてのサブエージェントが完了するのを待ってから、次の処理を行います：

1. すべての検出結果を単一のリストに統合します
2. 重複（同じファイルと行、およびタイプ）を削除します
3. .beagle/llm-artifacts-review.json と重複する検出結果を削除します
4. 一意の ID（1、2、3...）を割り当てます
5. 表示用にカテゴリ別にグループ化します

8. JSON レポートの作成

.beagle ディレクトリが存在しない場合は作成します。

mkdir -p .beagle

検出結果を .beagle/ai-writing-review.json に書き込みます。

{
  "version": "1.0.0",
  "created_at": "2025-01-15T10:30:00Z",
  "git_head": "abc1234",
  "scope": "changed",
  "files_scanned": 12,
  "commits_scanned": 5,
  "findings": [
    {
      "id": 1,
      "category": "vocabulary",
      "type": "ai_vocabulary_high",
      "file": "README.md",
      "line": 15,
      "original_text": "This library leverages cutting-edge algorithms to facilitate seamless data processing.",
      "description": "High-signal AI vocabulary: leverage, cutting-edge, facilitate, seamless",
      "suggestion": "This library uses streaming algorithms for fast data processing.",
      "risk": "Low",
      "fix_safety": "Safe",
      "fix_action": "rewrite"
    },
    {
      "id": 2,
      "category": "code_docs",
      "type": "tautological_docstring",
      "file": "src/auth.py",
      "line": 42,
      "original_text": "\"\"\"Get the user by ID.\"\"\"",
      "description": "Docstring restates function name get_user_by_id without adding value",
      "suggestion": "\"\"\"Raises UserNotFound if ID doesn't exist.\"\"\"",
      "risk": "Medium",
      "fix_safety": "Needs review",
      "fix_action": "rewrite"
    },
    {
      "id": 3,
      "category": "communication",
      "type": "chat_leak",
      "file": "git:commit:abc1234",
      "line": 0,
      "original_text": "Certainly! Here's the updated authentication flow",
      "description": "Chat leak in commit message: starts with 'Certainly! Here's'",
      "suggestion": "Update authentication flow",
      "risk": "Low",
      "fix_safety": "Safe",
      "fix_action": "rewrite"
    }
  ],
  "summary": {
    "total": 3,
    "by_category": {
      "vocabulary": 1,
      "code_docs": 1,
      "communication": 1
    },
    "by_risk": {
      "Low": 2,
      "Medium": 1
    },
    "by_fix_safety": {
      "Safe": 2,
      "Needs review": 1
    }
  }
}

9. 概要の表示

## AI Writing Review

**Scope:** Changed files from main
**Files scanned:** 12 | **Commits scanned:** 5

### Findings by Category

#### Vocabulary (1 issue)

1. [README.md:15] **AI vocabulary** (Low, Safe)
   - High-signal AI vocabulary: leverage, cutting-edge, facilitate, seamless
   - Suggestion: Rewrite with simple words

#### Code Docs (1 issue)

2. [src/auth.py:42] **Tautological docstring** (Medium, Needs review)
   - Docstring restates function name without adding value
   - Suggestion: Add meaningful information or delete

#### Communication (1 issue)

3. [git:commit:abc1234:0] **Chat leak** (Low, Safe)
   - Commit message starts with "Certainly! Here's"
   - Suggestion: Rewrite as imperative commit message

### Summary Table

| Category | Safe | Needs Review | Total |
|----------|------|--------------|-------|
| Vocabulary | 1 | 0 | 1 |
| Code Docs | 0 | 1 | 1 |
| Communication | 1 | 0 | 1 |
| **Total** | **2** | **1** | **3** |

### Next Steps

- Invoke the humanize-beagle skill to apply fixes
- Invoke the humanize-beagle skill with --dry-run to preview changes first
- Review the JSON report at `.beagle/ai-writing-review.json`

10. 検証

完了前に、以下の項目がすべて合格している必要があります（客観的なチェック）。

1. JSON ファイルが存在し、解析できること： .beagle/ai-writing-review.json が存在すること。または Gate 1 でスキャンせずに終了していること（その場合、JSON は不要です）。
2. JSON の妥当性： ファイルが存在する場合、python3 -c "import json; json.load(open('.beagle/ai-writing-review.json'))" が終了コード 0 で終了すること。
3. サブエージェントの成功： サブエージェントを起動した場合、それぞれがツールまたはランタイムの失敗なく処理を終えていること（起動に失敗した場合、完了したものとして最終 JSON を書き込まないでください）。
4. Git HEAD の取得： JSON が存在する場合、git_head が git rev-parse HEAD と一致すること（空でない文字列）。
5. 二重検出がないこと： .beagle/llm-artifacts-review.json が存在する場合、§4 のスキップルールに該当する file:line と重複タイプの検出結果がないこと。

# Verify JSON is valid (when file exists)
python3 -c "import json; json.load(open('.beagle/ai-writing-review.json'))" 2>/dev/null && echo "Valid JSON" || echo "Invalid JSON"

チェックに失敗した場合は、エラーを報告し、先に進まないでください。

各検出結果の出力形式

[FILE:LINE] ISSUE_TITLE
- Category: content | vocabulary | formatting | communication | filler | code_docs
- Type: specific_pattern_name
- Original: "the problematic text"
- Suggestion: "the improved text" or "delete"
- Risk: Low | Medium
- Fix Safety: Safe | Needs review

ルール

• 必ずこのスキルのパターンカタログと review-verification-protocol を先に読み込んでください
• エージェントがサブエージェントに対応しており、スキャン対象が 4 件以上の場合は、アーティファクトのグループごとに並列処理してください。それ以外の場合は、順次スキャンしてください
• すべての検出結果に file:line の参照を含めてください（Git アーティファクトには合成パスを使用）
• スキルに記載された誤検出を指摘しないでください
• .beagle/llm-artifacts-review.json の検出結果と重複させないでください
• 必要に応じて .beagle ディレクトリを作成してください
• 概要を表示する前に JSON レポートを書き込んでください

ゲート（順番に満たす条件）

アーティファクト（パス、終了コード、解析可能な出力）によって各合格条件を満たした場合にのみ先へ進んでください。「確認した」という内部的な主張だけでは不十分です。

1. 引数 → 対象範囲

   • 合格条件： スキャン対象となる具体的なパス（または git:commit:<sha> / git:pr:<n>）を列挙できること。対象が空の場合は「スキャン対象のファイルはありません…」というメッセージを出力し、.beagle/ai-writing-review.json を作成しないでください。

2. 対象範囲 → 実行

   • 合格条件： Prose、Code docs、および対象範囲に含まれる場合は Git のそれぞれについて、サブエージェントの処理結果が出ていること、または各検出結果に同じ構造化フィールドを含む同等のインライン処理が完了していること。

3. 統合 → 書き込み

   • 合格条件： 重複（同じ file:line とタイプ）を削除していること。.beagle/llm-artifacts-review.json が存在する場合は、§4 に従ってその検出結果との重複を除外していること。git_headがgit rev-parse HEAD` の出力と一致し、空でないこと。

4. JSON → 概要

   • 合格条件： python3 -c "import json; json.load(open('.beagle/ai-writing-review.json'))" が終了コード 0 で終了すること。

5. 検出結果 → 検証プロトコル

   • 合格条件： 報告する各問題について、指摘の根拠となった周辺の段落または関数を示せること（review-verification-protocol を参照）。

参考資料

開発者向けテキストにおける AI 生成文の検出

開発者向けアーティファクトに含まれる、AI 生成文に特徴的なパターンを検出します。こうしたパターンは信頼を損ない、ノイズを増やし、意味を曖昧にします。

パターンカテゴリ

カテゴリ	参照先	主な兆候
内容	references/content-patterns.md	宣伝的な表現、曖昧な権威付け、型にはまった構成、人工的な書き出し
語彙	references/vocabulary-patterns.md	AI 特有の単語レベル、コピュラの回避、修辞技法、類義語の循環、コミット内容の誇張
書式	references/formatting-patterns.md	太字の多用、絵文字による装飾、見出しの言い換え
コミュニケーション	references/communication-patterns.md	チャットの漏出、途中で打ち切る免責表現、迎合的な口調、謝罪を含むエラー
埋め草	references/filler-patterns.md	埋め草の表現、過剰な曖昧表現、汎用的な結論
コードドキュメント	references/code-docs-patterns.md	同語反復の docstring、自明なコードの説明、「この名詞は動詞する」という構文、網羅的な列挙

対象範囲

以下の種類の成果物をスキャンします。

成果物	ファイルパターン	備考
Markdown ドキュメント	*.md	README、ガイド、変更履歴
Docstring	*.py、*.ts、*.js、*.go、*.swift、*.rs、*.java、*.kt、*.rb、*.ex	言語固有の docstring 形式
コードコメント	Docstring と同じ	インラインコメントとブロックコメント
コミットメッセージ	git log の出力	合成パス git:commit:<sha> を使用
PR の説明	GitHub PR の本文	合成パス git:pr:<number> を使用

スキャン対象外

• 生成されたコード（ロックファイル、コンパイル済み出力、ベンダーディレクトリ）
• サードパーティのコンテンツ（コピーされたライセンステキスト、ベンダー提供のドキュメント）
• コードそのもの（変数名、プログラムで使用される文字列リテラル）
• テスト用フィクスチャとモックデータ

検出ルール

確信度の高い兆候（常に指摘）

以下のパターンは、AI 生成テキストを強く示すものです。

1. チャットの痕跡 — 「Certainly!」、「I'd be happy to」、「Great question!」、「Here's」で文を始める
2. 知識の期限に関する免責事項 — 「As of my last update」、「I cannot guarantee」
3. AI を強く示す語彙 — delve、utilize（「use」の意味で）、whilst、harnessing、paradigm、synergy
4. docstring 内の「This noun verbs」構文 — 「This function calculates」、「This method returns」
5. 定型的な書き出し — 「In today's fast-paced」、「In the world of」
6. へつらうコードコメント — 「Excellent approach!」、「Great implementation!」

確信度が中程度の兆候（文脈に応じて指摘）

2 つ以上が同時に現れる場合、またはパターンが繰り返される場合に指摘します。

1. AI を示す可能性が低い語彙の集積 — 1 つのセクション内に低確信度リストの単語が 3 つ以上ある
2. 定型的な構成 — README のセクションが、厳格な導入・本文・結論の構成になっている
3. 見出しの言い換え — 見出し直後の最初の文が見出しを言い換えている
4. 過度な婉曲表現 — 「might potentially」、「could possibly」、「it seems like it may」
5. 類義語の使い分け — 1 つのセクション内で同じ概念に異なる呼称を使っている
6. 太字の過剰使用 — 文の 30% 超に太字が含まれている

確信度の低い兆候（記録のみ）

言及はしますが、問題としては指摘しません。

1. 技術ドキュメント内の絵文字 — プロジェクトのスタイルとして意図されている可能性があります
2. 埋め草の表現 — 人間の文章でもよく使われるものがあります
3. 一般的な結論 — まとめのセクションでは適切な場合があります
4. コミットメッセージの詳細さ — 説明的なコミットメッセージを好むチームもあります

誤検出に関する注意

以下は AI 生成として指摘しないでください。

パターン	有効な理由
セキュリティドキュメント内の「Ensure」	セキュリティ要件で一般的に使われる用語です
テストカバレッジに関する説明内の「Comprehensive」	技術的に正確な説明です
API リファレンスドキュメント内のフォーマルな文体	リファレンス資料に期待される文体です
金融・ビジネス領域のコード内の「Leverage」	AI 由来の埋め草ではなく、ドメイン固有の意味があります
CLI ヘルプテキスト内の太字書式	一般的な慣例です
RFC/ADR 内の構造化された導入段落	これらの文書形式に期待される構成です
Python の __init__.py 内の「This module provides」	Python のモジュール docstring で慣用される表現です
ブログ記事内の修辞疑問文	カジュアルなコンテンツに適しています

統合

review-verification-protocol との連携

指摘を報告する前に、以下を行います。

1. 周辺の文脈（段落全体または関数全体）を確認します
2. そのパターンが単なるフォーマルな表現ではなく、AI に特徴的なものかを確認します
3. プロジェクトに、そのパターンに合致する確立された規約があるかを確認します
4. 意味を変えずに提案が明瞭さを高めることを確認します

llm-artifacts-detection との併用

コードレベルのパターン（同語反復のドックストリング、明白なコメント）は、llm-artifacts-detection のスタイル基準と重複します。両方のスキルを読み込んでいる場合：

• review-ai-writing は文章スタイル（読みやすさ）に焦点を当てます
• llm-artifacts-detection はコードアーティファクト（そもそも存在すべきかどうか）に焦点を当てます
• .beagle/llm-artifacts-review.json が存在する場合は、すでにそこに記録されている指摘をスキップします

出力形式

各指摘は次の形式で報告してください：

[FILE:LINE] ISSUE_TITLE
- Category: content | vocabulary | formatting | communication | filler | code_docs
- Type: specific_pattern_name
- Original: "the problematic text"
- Suggestion: "the improved text" or "delete"
- Risk: Low | Medium
- Fix Safety: Safe | Needs review

リスクレベル

• 低 — つなぎ言葉、明白なコメント、絵文字。削除すると意味を変えずに明瞭になります。
• 中 — 語彙の置き換え、構成の変更、ドックストリングの書き換え。不注意に行うと意味が変わる可能性があります。

修正の安全性

• 安全 — 機械的な置き換えまたは削除。判断は不要です。
• 要確認 — 書き換えには文脈の理解が必要です。置き換え後も意図が保たれていることを人間が確認してください。