Merge pull request #274 from ysk8hori/docs-0.26.0

ysk8hori · web-flow · commit 1ed6855ffdcd · 2025-07-04T08:12:02.000+09:00
docs: 構成の見直し
diff --git a/README.md b/README.md
@@ -181,49 +181,6 @@ Also, for large repositories, Mermaid may exceed the maximum amount of data that
 
 In that case, you need to narrow down the directories to include in the graph.
 
-### For AI Agents
-
-When using TypeScript Graph with AI agents, the `--stdout` option provides structured output that's easy to parse and analyze:
-
-```bash
-# Analyze codebase architecture and get both dependency graph and metrics
-tsg --stdout
-
-# Get only code metrics for quality assessment
-tsg --stdout metrics
-
-# Get only dependency relationships for architecture analysis
-tsg --stdout deps
-```
-
-**Example prompts for AI agents:**
-
-```
-Analyze this TypeScript codebase architecture:
-$(tsg --stdout deps)
-
-Identify circular dependencies and suggest refactoring strategies.
-```
-
-```
-Review code quality metrics:
-$(tsg --stdout metrics)
-
-Identify files with low maintainability index and high complexity that need refactoring.
-```
-
-```
-Full codebase analysis:
-$(tsg --stdout)
-
-Provide architectural insights and code quality recommendations.
-```
-
-```
-Review code quality for changes in the current branch:
-$(tsg --stdout --include $(git diff --name-only main | tr '\n' ' '))
-```
-
 ### Arguments or `--include`
 
 To narrow down the directories or files included in the graph, specify the paths or parts of the paths using either the argument or the `--include` option.
@@ -434,6 +391,49 @@ flowchart LR
 
 It makes it easier to share problems within the team. 👍
 
+### For AI Agents
+
+When using TypeScript Graph with AI agents, the `--stdout` option provides structured output that's easy to parse and analyze:
+
+```bash
+# Analyze codebase architecture and get both dependency graph and metrics
+tsg --stdout
+
+# Get only code metrics for quality assessment
+tsg --stdout metrics
+
+# Get only dependency relationships for architecture analysis
+tsg --stdout deps
+```
+
+**Example prompts for AI agents:**
+
+```
+Analyze this TypeScript codebase architecture:
+$(tsg --stdout deps)
+
+Identify circular dependencies and suggest refactoring strategies.
+```
+
+```
+Review code quality metrics:
+$(tsg --stdout metrics)
+
+Identify files with low maintainability index and high complexity that need refactoring.
+```
+
+```
+Full codebase analysis:
+$(tsg --stdout)
+
+Provide architectural insights and code quality recommendations.
+```
+
+```
+Review code quality for changes in the current branch:
+$(tsg --stdout --include $(git diff --name-only main | tr '\n' ' '))
+```
+
 ## Code Metrics Measurement
 
 This is a beta feature for measuring code metrics such as the Maintainability Index, Cyclomatic Complexity, and Cognitive Complexity. While these metrics are widely recognized, their reliability in TypeScript-specific contexts is not guaranteed. Nonetheless, they can serve as helpful indicators for evaluating code quality.
@@ -560,7 +560,7 @@ tsg --stdout
 # Output only metrics
 tsg --stdout metrics
 
-# Output only dependency graph  
+# Output only dependency graph
 tsg --stdout deps
 
 # Output both (explicit)
@@ -629,4 +629,3 @@ flowchart
   - Maintainability Index
   - Cyclomatic Complexity
   - Cognitive Complexity
-
diff --git a/docs/README_en.md b/docs/README_en.md
@@ -181,49 +181,6 @@ Also, for large repositories, Mermaid may exceed the maximum amount of data that
 
 In that case, you need to narrow down the directories to include in the graph.
 
-### For AI Agents
-
-When using TypeScript Graph with AI agents, the `--stdout` option provides structured output that's easy to parse and analyze:
-
-```bash
-# Analyze codebase architecture and get both dependency graph and metrics
-tsg --stdout
-
-# Get only code metrics for quality assessment
-tsg --stdout metrics
-
-# Get only dependency relationships for architecture analysis
-tsg --stdout deps
-```
-
-**Example prompts for AI agents:**
-
-```
-Analyze this TypeScript codebase architecture:
-$(tsg --stdout deps)
-
-Identify circular dependencies and suggest refactoring strategies.
-```
-
-```
-Review code quality metrics:
-$(tsg --stdout metrics)
-
-Identify files with low maintainability index and high complexity that need refactoring.
-```
-
-```
-Full codebase analysis:
-$(tsg --stdout)
-
-Provide architectural insights and code quality recommendations.
-```
-
-```
-Review code quality for changes in the current branch:
-$(tsg --stdout --include $(git diff --name-only main | tr '\n' ' '))
-```
-
 ### Arguments or `--include`
 
 To narrow down the directories or files included in the graph, specify the paths or parts of the paths using either the argument or the `--include` option.
@@ -434,6 +391,49 @@ flowchart LR
 
 It makes it easier to share problems within the team. 👍
 
+### For AI Agents
+
+When using TypeScript Graph with AI agents, the `--stdout` option provides structured output that's easy to parse and analyze:
+
+```bash
+# Analyze codebase architecture and get both dependency graph and metrics
+tsg --stdout
+
+# Get only code metrics for quality assessment
+tsg --stdout metrics
+
+# Get only dependency relationships for architecture analysis
+tsg --stdout deps
+```
+
+**Example prompts for AI agents:**
+
+```
+Analyze this TypeScript codebase architecture:
+$(tsg --stdout deps)
+
+Identify circular dependencies and suggest refactoring strategies.
+```
+
+```
+Review code quality metrics:
+$(tsg --stdout metrics)
+
+Identify files with low maintainability index and high complexity that need refactoring.
+```
+
+```
+Full codebase analysis:
+$(tsg --stdout)
+
+Provide architectural insights and code quality recommendations.
+```
+
+```
+Review code quality for changes in the current branch:
+$(tsg --stdout --include $(git diff --name-only main | tr '\n' ' '))
+```
+
 ## Code Metrics Measurement
 
 This is a beta feature for measuring code metrics such as the Maintainability Index, Cyclomatic Complexity, and Cognitive Complexity. While these metrics are widely recognized, their reliability in TypeScript-specific contexts is not guaranteed. Nonetheless, they can serve as helpful indicators for evaluating code quality.
@@ -536,7 +536,7 @@ You can monitor file changes in real time and display metrics such as the Mainta
 tsg --watch-metrics
 ```
 
-![tsg --watch-metrics result](docs/img/watch-metrics.png)
+![tsg --watch-metrics result](/docs/img/watch-metrics.png)
 
 The values in `()` represent the difference from when monitoring started. Improvements are displayed in green, while regressions are shown in red. Whether an increase or decrease is better depends on the metric. The following table outlines the preferred directions for each metric:
 
@@ -560,7 +560,7 @@ tsg --stdout
 # Output only metrics
 tsg --stdout metrics
 
-# Output only dependency graph  
+# Output only dependency graph
 tsg --stdout deps
 
 # Output both (explicit)
@@ -629,4 +629,3 @@ flowchart
   - Maintainability Index
   - Cyclomatic Complexity
   - Cognitive Complexity
-
diff --git a/docs/README_ja.md b/docs/README_ja.md
@@ -87,7 +87,7 @@ npm install --global @ysk8hori/typescript-graph
 | `-w, --watch-metrics`     | ファイルの変更をリアルタイムで監視し、変更が発生するたびに Maintainability Index、Cyclomatic Complexity、Cognitive Complexity などのメトリクスを表示します。継続的な品質チェックに利用可能です。                                                                           |
 | `--config-file`           | 設定ファイルへの相対パスを指定します（カレントディレクトリまたは -d, --dir で指定された場所から）。デフォルトは .tsgrc.json です。                                                                                                                                         |
 | `--vue` (experimental)    | `.vue` ファイルも対象とします。Node.js の `fs.mkdtempSync` によって作業ディレクトリを作成し、そこへ tsc 対象となるファイルと `.vue` ファイルをコピーして解析します。`.vue` ファイルは `.vue.ts` へとリネームしますが、すでにそのファイルが存在する場合はリネームしません。 |
-| `--stdout [types...]`     | 構造化データを標準出力に出力します。types: `metrics`, `deps`, または省略で全て（デフォルト: 全て）。例: `--stdout` (全て), `--stdout metrics` (メトリクスのみ), `--stdout deps` (依存グラフのみ), `--stdout metrics deps` (両方) |
+| `--stdout [types...]`     | 構造化データを標準出力に出力します。types: `metrics`, `deps`, または省略で全て（デフォルト: 全て）。例: `--stdout` (全て), `--stdout metrics` (メトリクスのみ), `--stdout deps` (依存グラフのみ), `--stdout metrics deps` (両方)                                           |
 | `-h, --help`              | コマンドのヘルプを表示します。                                                                                                                                                                                                                                             |
 
 ## 使い方
@@ -181,49 +181,6 @@ flowchart
 
 その場合、グラフに含めるディレクトリを絞り込む必要があります。
 
-### AI エージェント向け
-
-AI エージェントと TypeScript Graph を使用する場合、`--stdout` オプションで構造化された出力を提供し、解析しやすい形式でデータを得ることができます：
-
-```bash
-# コードベースアーキテクチャを分析し、依存関係グラフとメトリクスの両方を取得
-tsg --stdout
-
-# 品質評価のためのコードメトリクスのみを取得
-tsg --stdout metrics
-
-# アーキテクチャ分析のための依存関係のみを取得
-tsg --stdout deps
-```
-
-**AI エージェントのためのプロンプト例:**
-
-```
-このTypeScriptコードベースのアーキテクチャを分析してください：
-$(tsg --stdout deps)
-
-循環依存を特定し、リファクタリング戦略を提案してください。
-```
-
-```
-コード品質メトリクスをレビューしてください：
-$(tsg --stdout metrics)
-
-保守性指数が低く、複雑度が高いファイルを特定し、リファクタリングが必要なファイルを見つけてください。
-```
-
-```
-完全なコードベース分析：
-$(tsg --stdout)
-
-アーキテクチャの洞察とコード品質の推奨事項を提供してください。
-```
-
-```
-現在のブランチでの変更のコード品質をレビューしてください：
-$(tsg --stdout --include $(git diff --name-only main | tr '\n' ' '))
-```
-
 ### 引数または `--include` オプション
 
 グラフに含めるディレクトリやファイルを絞り込むには、引数または `--include` オプションでパスまたはその一部を指定します。
@@ -437,6 +394,49 @@ flowchart LR
 
 さらにチームと問題の共有がしやすくなりました 👍
 
+### AI エージェント向け
+
+AI エージェントと TypeScript Graph を使用する場合、`--stdout` オプションで構造化された出力を提供し、解析しやすい形式でデータを得ることができます：
+
+```bash
+# コードベースアーキテクチャを分析し、依存関係グラフとメトリクスの両方を取得
+tsg --stdout
+
+# 品質評価のためのコードメトリクスのみを取得
+tsg --stdout metrics
+
+# アーキテクチャ分析のための依存関係のみを取得
+tsg --stdout deps
+```
+
+**AI エージェントのためのプロンプト例:**
+
+```
+このTypeScriptコードベースのアーキテクチャを分析してください：
+$(tsg --stdout deps)
+
+循環依存を特定し、リファクタリング戦略を提案してください。
+```
+
+```
+コード品質メトリクスをレビューしてください：
+$(tsg --stdout metrics)
+
+保守性指数が低く、複雑度が高いファイルを特定し、リファクタリングが必要なファイルを見つけてください。
+```
+
+```
+完全なコードベース分析：
+$(tsg --stdout)
+
+アーキテクチャの洞察とコード品質の推奨事項を提供してください。
+```
+
+```
+現在のブランチでの変更のコード品質をレビューしてください：
+$(tsg --stdout --include $(git diff --name-only main | tr '\n' ' '))
+```
+
 ## コードメトリクスの測定
 
 保守性指数（Maintainability Index）、サイクロマティック複雑度（Cyclomatic Complexity）、認知的複雑度（Cognitive Complexity）などのコード・メトリクスを測定するベータ機能です。これらのメトリクスは一般的に知られていますが、TypeScript に当てはめた場合には信頼性が高いものではありません。それでも、コードの品質について考える際の指標にはなりうると考えています。
@@ -539,7 +539,7 @@ function volume(): number {
 tsg --watch-metrics
 ```
 
-![tsg --watch-metrics result](img/watch-metrics.png)
+![tsg --watch-metrics result](/docs/img/watch-metrics.png)
 
 `()` 内の値は、監視開始時からの差分です。より良い値へと変わった場合は緑で、より悪い値へ変わった場合は赤で表示します。値の増減の良し悪しはメトリクスによって異なります。以下に対応表を記載します。
 
@@ -618,4 +618,3 @@ flowchart
   - 保守性指数
   - サイクロマティック複雑度
   - 認知的複雑度
-
