feat: テクニカルライティングガイドラインを追加し、READMEを更新

azu · azu · commit 85490a5d0ac9 · 2025-06-29T13:57:10.000+09:00
fix #3
diff --git a/README.md b/README.md
@@ -1,6 +1,7 @@
 # textlint-rule-preset-ai-writing
 
-AIが生成した文章によく見られる記述パターンを検出し、より自然な日本語表現を促すtextlintルールプリセットです。
+AIが生成した文章によく見られる記述パターンを検出することができます。
+より自然な日本語表現を促すtextlintルールプリセットです。
 
 ## 原則
 
@@ -11,7 +12,24 @@ AIが生成した文章によく見られる記述パターンを検出し、よ
 ### 1. no-ai-list-formatting
 リストアイテムで機械的な印象を与える可能性のある記述パターンを検出します。
 
-#### 1-1. リストアイテムの強調表現
+### 2. no-ai-hype-expressions
+AIライティングで過度に使用されがちな誇張表現やハイプ的な表現を検出します。
+
+### 3. no-ai-emphasis-patterns
+AIが機械的に生成しがちな強調パターンを検出します。
+
+### 4. ai-tech-writing-guideline
+テクニカルライティングのベストプラクティスに基づいて、文書品質の改善提案を行います。
+詳細なガイドラインについては [docs/tech-writing-guidelines.md](./docs/tech-writing-guidelines.md) を参照してください。
+
+#### 検出される内容
+- 簡潔性: 冗長表現の排除（「まず」→「まず」など）
+- 明確性: 能動態の使用推奨（受動態から能動態への変更提案）
+- 具体性: 抽象的表現の具体化（「高速な」→「50ms未満の」など）
+- 一貫性: 用語と表現の統一（同一対象への異なる用語使用の検出）
+- 構造化: 文の長さと情報整理（長い文の分割提案など）
+
+#### 4-1. リストアイテムの強調表現
 - `allows`: 指定したパターンにマッチする場合、エラーを報告しません
   - 文字列: `"許可したいテキスト"`
   - 正規表現: `"/パターン/フラグ"` (例: `"/以下のような.*/"`)
@@ -30,11 +48,13 @@ AIが生成した文章によく見られる記述パターンを検出し、よ
 - **注意**: 注意が必要な項目です
 ```
 
-書き換えた例
+書き換えた例:
 ```markdown
 - 重要な項目: これは重要な項目です
 - 注意事項: 注意が必要な項目です
 ```
+- 注意事項: 注意が必要な項目です
+```
 
 #### 1-2. 絵文字を使ったリストアイテム
 
@@ -170,6 +190,15 @@ Via `.textlintrc`(Recommended)
                 "disableAbsolutenessPatterns": false,
                 "disableAbstractPatterns": false,
                 "disabledPredictivePatterns": false
+            },
+            "ai-tech-writing-guideline": {
+                "allows": ["許可したいテキスト", "/正規表現パターン/"],
+                "disableRedundancyGuidance": false,
+                "disableVoiceGuidance": false,
+                "disableClarityGuidance": false,
+                "disableConsistencyGuidance": false,
+                "disableStructureGuidance": false,
+                "enableDocumentAnalysis": true
             }
         }
     }
diff --git a/docs/tech-writing-guidelines.md b/docs/tech-writing-guidelines.md
@@ -0,0 +1,162 @@
+# テクニカルライティングガイドライン
+
+効果的なテクニカルライティングの原則に基づいた、自然で読みやすい技術文書作成のためのガイドラインです。
+
+## 基本原則：効果的なテクニカルライティングの「7つのC」
+
+優れたテクニカルドキュメントは以下の品質を持ちます：
+
+- **Clear（明確）**: 曖昧さがなく、容易に理解できる
+- **Concise（簡潔）**: 必要な情報を最小限の言葉で表現
+- **Correct（正確）**: 文法、事実、技術的内容に誤りがない
+- **Coherent（一貫）**: 論理的に結びつき、スムーズに流れる
+- **Concrete（具体的）**: 抽象的でなく、測定可能で明確
+- **Complete（完全）**: 必要な情報がすべて含まれている
+- **Courteous（丁寧）**: 読者を意識した適切なトーンと構成
+
+## 1. 簡潔性の原則（Conciseness）
+
+### 冗長表現の排除
+
+#### 検出される表現とより良い代替案
+
+| 検出される表現 | 推奨される表現 | 理由 |
+|---------------|---------------|------|
+| まず最初に | まず / 最初に | 意味の重複 |
+| あらかじめ予測 | 予測 | 「予測」自体が事前の概念を含む |
+| することができます | できます / します | 不必要な助動詞の重複 |
+| する必要があります | してください / します | より直接的な表現 |
+| 言うまでもなく | （削除） | 不要な前置き |
+
+#### 改善例
+
+```markdown
+❌ まず最初に設定ファイルを開く必要があります。
+✅ まず、設定ファイルを開きます。
+
+❌ このAPIを使用することができます。
+✅ このAPIを使用できます。
+```
+
+## 2. 明確性の原則（Clarity）
+
+### 能動態の使用と具体的な動詞
+
+#### 受動態から能動態への変更
+
+| 受動的表現 | 能動的表現 | 改善効果 |
+|-----------|-----------|---------|
+| 処理が行われます | システムが処理します | 主語が明確 |
+| データの変更を行う | データを変更する | 直接的な動作 |
+| によって実行される | ○○が実行する | 行為者が明確 |
+
+#### 改善例
+
+```markdown
+❌ データの検証が行われます。
+✅ システムがデータを検証します。
+
+❌ ファイルの変更を行ってください。
+✅ ファイルを変更してください。
+```
+
+## 3. 具体性の原則（Concreteness）
+
+### 抽象的表現の具体化
+
+#### 曖昧な表現と具体的な代替案
+
+| 抽象的表現 | 具体的表現の例 | 改善効果 |
+|-----------|---------------|---------|
+| 高速なパフォーマンス | 50ms未満の応答時間 | 測定可能な基準 |
+| 大幅に向上 | 従来比200%向上 | 定量的な情報 |
+| 効率的な | メモリ使用量を30%削減 | 具体的な効果 |
+| 適切な | セキュリティ基準に準拠した | 明確な判断基準 |
+
+#### 改善例
+
+```markdown
+❌ このAPIは高速なパフォーマンスを提供します。
+✅ このAPIは50ms未満で応答します。
+
+❌ 大幅にパフォーマンスが向上しました。
+✅ 処理速度が従来比200%向上しました。
+```
+
+## 4. 一貫性の原則（Consistency）
+
+### 用語と表現の統一
+
+#### よくある不一致パターン
+
+| 不一致の例 | 統一すべき表現 | 注意点 |
+|-----------|---------------|--------|
+| ユーザー/クライアント/顧客 | プロジェクトで統一 | 同一対象は同一用語 |
+| 設定画面/設定ページ/環境設定 | UI名称で統一 | 機能名は正確に |
+| です・ます調/だ・である調 | 文書全体で統一 | 文体の混在を避ける |
+
+#### 改善例
+
+```markdown
+❌ ユーザーがログインし、クライアントが設定を変更します。
+✅ ユーザーがログインし、ユーザーが設定を変更します。
+
+❌ 設定画面を開き、設定ページで変更します。
+✅ 設定画面を開き、設定画面で変更します。
+```
+
+## 5. 構造化の原則（Structure）
+
+### 情報の論理的整理
+
+#### 文の長さと構造
+
+- **一文一義**: 一つの文には一つの主要なアイデアのみ
+- **適切な長さ**: 50文字を超える文は分割を検討
+- **論理的順序**: 時系列や重要度に基づいた情報配置
+
+#### 改善例
+
+```markdown
+❌ この機能は複数のオプションを提供し、ユーザーが柔軟に設定でき、
+   パフォーマンスも向上し、セキュリティも強化されています。
+
+✅ この機能は複数のオプションを提供します。
+   ユーザーは柔軟に設定できます。
+   パフォーマンスが向上し、セキュリティも強化されています。
+```
+
+### リストと見出しの活用
+
+- 連続する手順は番号付きリスト
+- 関連項目は箇条書き
+- 階層構造は見出しレベルで表現
+
+## 実装での考慮事項
+
+### ルールの適用レベル
+
+このガイドラインは以下の優先順位で適用されます：
+
+1. **正確性**: 技術的事実の正確性が最優先
+2. **明確性**: 読者の理解を妨げない表現
+3. **簡潔性**: 文書の目的に応じて調整
+4. **丁寧さ**: 読者層に適したトーン
+
+### カスタマイズ
+
+プロジェクトの特性に応じて：
+
+- 専門用語の定義と統一
+- 読者層に応じた説明レベル
+- 組織固有のスタイルガイド
+
+## 参考資料
+
+- [textlint](https://textlint.github.io/)
+- [JTF日本語標準スタイルガイド](https://www.jtf.jp/tips/styleguide)
+- [技術文書作成のベストプラクティス](https://developers.google.com/style)
+
+---
+
+このガイドラインは `ai-tech-writing-guideline` ルールの基準として使用されています。
diff --git a/lint-README.sh b/lint-README.sh
@@ -0,0 +1,11 @@
+#! /bin/bash
+set -ex
+
+mkdir -p tmp/
+npm install --save-dev . textlint technological-book-corpus-ja --prefix tmp/
+cd tmp
+# README.mdのチェックを行う
+./node_modules/.bin/textlint --preset ai-writing ../README.md
+
+# 元のディレクトリに戻る
+trap 'cd -' EXIT
diff --git a/package.json b/package.json
@@ -35,8 +35,9 @@
     "format": "prettier --write \"**/*.{js,jsx,ts,tsx,css}\"",
     "prepare": "git config --local core.hooksPath .githooks",
     "prepublishOnly": "npm run build",
-    "test": "npm run test:unit && npm run lint:text",
+    "test": "npm run test:unit && npm run lint:text && npm run lint:README",
     "lint:text": "textlint README.md",
+    "lint:README": "bash lint-README.sh",
     "test:unit": "textlint-scripts test",
     "watch": "textlint-scripts build --watch"
   },
diff --git a/src/index.ts b/src/index.ts
@@ -1,17 +1,22 @@
 import noAiListFormatting from "./rules/no-ai-list-formatting";
 import noAiHypeExpressions from "./rules/no-ai-hype-expressions";
 import noAiEmphasisPatterns from "./rules/no-ai-emphasis-patterns";
+import aiTechWritingGuideline from "./rules/ai-tech-writing-guideline";
 
 const preset = {
     rules: {
         "no-ai-list-formatting": noAiListFormatting,
         "no-ai-hype-expressions": noAiHypeExpressions,
-        "no-ai-emphasis-patterns": noAiEmphasisPatterns
+        "no-ai-emphasis-patterns": noAiEmphasisPatterns,
+        "ai-tech-writing-guideline": aiTechWritingGuideline
     },
     rulesConfig: {
         "no-ai-list-formatting": true,
         "no-ai-hype-expressions": true,
-        "no-ai-emphasis-patterns": true
+        "no-ai-emphasis-patterns": true,
+        "ai-tech-writing-guideline": {
+            severity: "info"
+        }
     }
 };
 
diff --git a/src/rules/ai-tech-writing-guideline.ts b/src/rules/ai-tech-writing-guideline.ts
diff --git a/test/rules/ai-tech-writing-guideline.test.ts b/test/rules/ai-tech-writing-guideline.test.ts
