Skip to content

docs: README.mdのルール説明を統一フォーマットに整理 #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 5, 2025
Merged

docs: README.mdのルール説明を統一フォーマットに整理 #20

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
292 changes: 130 additions & 162 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,14 +74,123 @@ MCPサーバの詳しい設定方法は [textlint MCP documentation](https://tex

リストアイテムで機械的な印象を与える可能性のある記述パターンを検出します。

#### 検出される例

```markdown
- **重要**: これは重要な項目です
- **注意**: 注意が必要な項目です
- ✅ 完了した項目
- ❌ 失敗した項目
- 💡 アイデア項目
- 🔥 ホットな話題
- 🚀 開始準備完了
- ⭐ 重要項目
- 🎯 目標設定
- 📝 メモ項目
```

#### より自然な表現

```markdown
- 重要な項目: これは重要な項目です
- 注意事項: 注意が必要な項目です
- 完了した項目
- 失敗した項目
- アイデア項目
- 注目の話題
- 開始準備完了
- 重要項目
- 目標設定
- メモ項目
```

#### オプション

- `allows`: 指定したパターンにマッチする場合、エラーを報告しません
- 文字列: `"許可したいテキスト"`
- 正規表現: `"/パターン/フラグ"` (例: `"/重要.*/i"`)
- `disableBoldListItems`: `true`にすると強調リストアイテムの検出を無効にする
- `disableEmojiListItems`: `true`にすると絵文字リストアイテムの検出を無効にする

### no-ai-hype-expressions

AIライティングで過度に使用されがちな誇張表現やハイプ的な表現を検出します。

#### 検出される例

```markdown
革命的な技術で業界を変えます。
これはゲームチェンジャーです。
世界初のソリューションを提供します。
究極のパフォーマンスを実現します。
完全に問題を解決します。
すべての課題を解決します。
最高の品質を保証します。
魔法のように動作します。
奇跡的な結果を生み出します。
可能性を解き放つソリューションです。
AIを民主化するプラットフォームです。
業務をスーパーチャージします。
業界を再定義する革新です。
未来を変える技術です。
パラダイムシフトを起こします。
不可避の変化が起こります。
次世代のソリューションです。
```

#### より自然な表現

```markdown
効果的な技術で業界に変化をもたらします。
これは大きな変化をもたらすでしょう。
新しいソリューションを提供します。
高いパフォーマンスを実現します。
多くの問題を解決します。
主要な課題を解決します。
高い品質を保証します。
スムーズに動作します。
優れた結果を生み出します。
新たな機会を創出するソリューションです。
AIを利用しやすくするプラットフォームです。
業務を効率化します。
業界に新しい視点をもたらす革新です。
将来に影響を与える技術です。
大きな変化を起こします。
重要な変化が起こるでしょう。
新しいソリューションです。
```

#### オプション

- `allows`: 指定したパターンにマッチする場合、エラーを報告しません
- 文字列: `"許可したいテキスト"`
- 正規表現: `"/パターン/フラグ"` (例: `"/革命的な.*/"`)
- `disableAbsolutenessPatterns`: `true`にすると絶対性・完全性を演出する表現の検出を無効にする
- `disableAbstractPatterns`: `true`にすると抽象的・感覚的効果を演出する表現の検出を無効にする
- `disabledPredictivePatterns`: `true`にすると権威的・予言的な表現の検出を無効にする

### no-ai-emphasis-patterns

AIが機械的に生成しがちな強調パターンを検出します。

#### 検出される例

```markdown
これは**非常に**重要な項目です。
**注意**してください。
```

#### より自然な表現

```markdown
これは重要な項目です。
注意してください。
```

#### オプション

- `allows`: 指定したパターンにマッチする場合、エラーを報告しません

### no-ai-colon-continuation

コロンの直後にブロック要素が続く英語的なパターンを検出します。日本語として自然な表現を促進するルールです。
Expand All @@ -107,7 +216,7 @@ command
- 具体的な例
````

#### より自然な日本語表現
#### より自然な表現

````markdown
実行方法は以下の通りです。
Expand All @@ -130,17 +239,21 @@ command
- 具体的な例
````

#### オプション

- `allows`: 指定したパターンにマッチする場合、エラーを報告しません
- 文字列: `"許可したいテキスト"`
- 正規表現: `"/パターン/フラグ"` (例: `"/使用方法.*/i"`)
- `disableCodeBlock`: `true`にするとコロン後のコードブロック検出を無効にする
- `disableList`: `true`にするとコロン後のリスト検出を無効にする
- `disableQuote`: `true`にするとコロン後の引用検出を無効にする
- `disableTable`: `true`にするとコロン後のテーブル検出を無効にする

### ai-tech-writing-guideline

テクニカルライティングのベストプラクティスに基づいて、文書品質の改善提案を行います。
詳細なガイドラインについては [docs/tech-writing-guidelines.md](./docs/tech-writing-guidelines.md) を参照してください。

#### 推奨する組み合わせ

このルールは [textlint-rule-preset-ja-technical-writing](https://github.com/textlint-ja/textlint-rule-preset-ja-technical-writing) との組み合わせを推奨します。
`ja-technical-writing` はfalse positiveが少ない確実なルールセットで、基本的な日本語技術文書の品質を担保します。
本ルール（`ai-tech-writing-guideline`）は、より高度な文書品質向上のためのサジェストとして使用することを想定しています。

#### 検出される内容

- 簡潔性: 冗長表現の排除
Expand All @@ -153,145 +266,20 @@ command
- 一貫性: 用語と表現の統一（同一対象への異なる用語使用の検出）
- 構造化: 文の長さと情報整理（長い文の分割提案など）

#### リストアイテムの強調表現
#### オプション

- `allows`: 指定したパターンにマッチする場合、エラーを報告しません
- 文字列: `"許可したいテキスト"`
- 正規表現: `"/パターン/フラグ"` (例: `"/以下のような.*/"`)

#### no-ai-hype-expressions

- `allows`: 指定したパターンにマッチする場合、エラーを報告しません
- 文字列: `"許可したいテキスト"`
- 正規表現: `"/パターン/フラグ"` (例: `"/革命的な.*/"`)
- `disableAbsolutenessPatterns`: `true`にすると絶対性・完全性を演出する表現の検出を無効にする
- `disableAbstractPatterns`: `true`にすると抽象的・感覚的効果を演出する表現の検出を無効にする
- `disabledPredictivePatterns`: `true`にすると権威的・予言的な表現の検出を無効にしますパターン

検出される例:
- `severity`: `"info"`にするとサジェストとして扱う
- `disableRedundancyGuidance`: `true`にすると冗長性の検出を無効にする
- `disableVoiceGuidance`: `true`にすると能動態・受動態の検出を無効にする
- `disableClarityGuidance`: `true`にすると明確性の検出を無効にする
- `disableConsistencyGuidance`: `true`にすると一貫性の検出を無効にする
- `disableStructureGuidance`: `true`にすると構造化の検出を無効にする
- `enableDocumentAnalysis`: `true`にすると文書全体の分析を有効にする

```markdown
- **重要**: これは重要な項目です
- **注意**: 注意が必要な項目です
```

書き換えた例:

```markdown
- 重要な項目: これは重要な項目です
- 注意事項: 注意が必要な項目です
```

#### 絵文字を使ったリストアイテム

AIが機械的に使いがちな装飾的な絵文字の使用を検出します。
検出対象は、特に「華やか」で機械的な印象を与える絵文字に限定されています。

検出される例:

```markdown
- ✅ 完了した項目
- ❌ 失敗した項目
- 💡 アイデア項目
- 🔥 ホットな話題
- 🚀 開始準備完了
- ⭐ 重要項目
- 🎯 目標設定
- 📝 メモ項目
```

書き換えた例:

```markdown
- 完了した項目
- 失敗した項目
- アイデア項目
- 注目の話題
- 開始準備完了
- 重要項目
- 目標設定
- メモ項目
```

注意: 普通の絵文字（😀, 🍎, 🐱, 🌸など）は検出されません。

### 2. no-ai-hype-expressions

AIライティングで過度に使用されがちな誇張表現やハイプ的な表現を検出します。自然で読みやすい文章を促進するためのルールです。

#### 絶対性・完全性を演出する表現

検出される例:

```markdown
革命的な技術で業界を変えます。
これはゲームチェンジャーです。
世界初のソリューションを提供します。
究極のパフォーマンスを実現します。
完全に問題を解決します。
すべての課題を解決します。
最高の品質を保証します。
```

書き換えた例:

```markdown
効果的な技術で業界に変化をもたらします。
これは大きな変化をもたらすでしょう。
新しいソリューションを提供します。
高いパフォーマンスを実現します。
多くの問題を解決します。
主要な課題を解決します。
高い品質を保証します。
```

#### 抽象的・感覚的効果を演出する表現

検出される例:

```markdown
魔法のように動作します。
奇跡的な結果を生み出します。
可能性を解き放つソリューションです。
AIを民主化するプラットフォームです。
業務をスーパーチャージします。
```

書き換えた例:

```markdown
スムーズに動作します。
優れた結果を生み出します。
新たな機会を創出するソリューションです。
AIを利用しやすくするプラットフォームです。
業務を効率化します。
```

#### 権威的・予言的な表現

検出される例:

```markdown
業界を再定義する革新です。
未来を変える技術です。
パラダイムシフトを起こします。
不可避の変化が起こります。
次世代のソリューションです。
```

書き換えた例:

```markdown
業界に新しい視点をもたらす革新です。
将来に影響を与える技術です。
大きな変化を起こします。
重要な変化が起こるでしょう。
新しいソリューションです。
```

### 推奨構成: ja-technical-writing との組み合わせ
#### 推奨する組み合わせ

基本的な日本語技術文書の品質担保と、より高度な文書品質向上の組み合わせ:
このルールは [textlint-rule-preset-ja-technical-writing](https://github.com/textlint-ja/textlint-rule-preset-ja-technical-writing) との組み合わせを推奨します。

```json
{
Expand Down Expand Up @@ -349,26 +337,6 @@ AIを利用しやすくするプラットフォームです。
}
```

### Options説明

#### no-ai-list-formatting

- `allows`: 指定したパターンにマッチする場合、エラーを報告しません
- 文字列: `"許可したいテキスト"`
- 正規表現: `"/パターン/フラグ"` (例: `"/重要.*/i"`)
- `disableBoldListItems`: `true`にすると強調リストアイテムの検出を無効にする
- `disableEmojiListItems`: `true`にすると絵文字リストアイテムの検出を無効にする

#### no-ai-colon-continuation

- `allows`: 指定したパターンにマッチする場合、エラーを報告しません
- 文字列: `"許可したいテキスト"`
- 正規表現: `"/パターン/フラグ"` (例: `"/使用方法.*/i"`)
- `disableCodeBlock`: `true`にするとコロン後のコードブロック検出を無効にする
- `disableList`: `true`にするとコロン後のリスト検出を無効にする
- `disableQuote`: `true`にするとコロン後の引用検出を無効にする
- `disableTable`: `true`にするとコロン後のテーブル検出を無効にする

### 正規表現パターンの使用例

`allows`オプションでは、[regexp-string-matcher](https://github.com/textlint/regexp-string-matcher)の形式で正規表現パターンを指定できます。
Expand Down