Skip to content

Commit 2814d37

Browse files
ysk8horiysk8hori
authored
Merge pull request #270 from ysk8hori/feature/ai-structured-output
feat: ツール・AI統合のための --stdout オプションを追加
2 parents 37adb68 + 2bce46c commit 2814d37

File tree

11 files changed

+494
-16
lines changed

11 files changed

+494
-16
lines changed

‎.github/workflows/integration-testing.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ jobs:
1212

1313
strategy:
1414
matrix:
15-
node-version: [18.x]
15+
node-version: [20.x]
1616
# See supported Node.js release schedule at https://nodejs.org/en/about/releases/
1717

1818
steps:

‎CLAUDE.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Claude Code 開発ガイドライン
2+
3+
このドキュメントは、Claude Code を使った効率的なソフトウェア開発のワークフローをまとめたものです。
4+
5+
## 📋 開発フロー
6+
7+
### 1. 準備・計画
8+
9+
- [ ] 既存コードベースの理解（README.md、アーキテクチャ調査）
10+
- [ ] 要件の明確化と TodoWrite でタスクリスト作成
11+
- [ ] ブランチ作成（`feature/`, `fix/`, `chore/`等）
12+
- [ ] 実装方針の決定（技術選択、既存パターンとの整合性）
13+
- [ ] 実装箇所の特定と影響範囲の調査
14+
15+
### 2. 実装
16+
17+
- [ ] 型定義から開始
18+
- [ ] t-wada 流 TDD で段階的実装 (`npm run test:watch`)
19+
- [ ] 既存 conventions に従い、型安全性を重視
20+
- [ ] 保守容易性を30以上維持 (`tsg --json --metrics`)
21+
- [ ] ビルド・テスト確認を継続的に実行
22+
23+
### 3. 完了
24+
25+
- [ ] integration テスト追加・実行 (`npm run test:integration`)
26+
- [ ] 実際の動作確認
27+
- [ ] CLAUDE.md 更新
28+
- [ ] git commit（詳細なメッセージ）
29+
- [ ] プルリクエスト作成
30+
31+
## 🛠️ 技術方針
32+
33+
### コード品質
34+
35+
- **TDD**: 小さなタスクリストを作成し RED-GREEN-REFACTOR を回す
36+
- **DRY原則**: 可読性と疎結合を優先した適度な抽象化
37+
- **既存パターン踏襲**: プロジェクトの conventions を維持
38+
- **Clean stdout**: パイプライン処理に配慮した出力設計
39+
40+
### ツール活用
41+
42+
- **TodoWrite/TodoRead**: タスク管理の徹底
43+
- **Task tool**: 複雑な検索・調査作業
44+
- **Multiple tool calls**: 並列処理による効率化
45+
- **Grep, Glob, Read**: 既存コード調査の戦略的活用
46+
47+
## 📖 ドキュメント構造
48+
49+
### ドキュメント階層
50+
51+
- **README.md**: ベースとなるドキュメント（英語）
52+
- **docs/README_en.md**: README.mdのコピー
53+
- **docs/README_ja.md**: README.mdの日本語訳
54+
55+
### 更新手順
56+
57+
1. README.mdを更新
58+
2. docs/README_en.mdに同期
59+
3. docs/README_ja.mdを日本語翻訳で更新
60+
61+
### 留意点
62+
63+
- **画像パス**: README.mdでは`docs/img/*`、docs内では`img/*`
64+
65+
## 📝 品質基準
66+
67+
### 実装品質
68+
69+
- [ ] TypeScript エラーなし
70+
- [ ] 既存テスト通過
71+
- [ ] 新機能テストカバー
72+
- [ ] パフォーマンス影響なし
73+
74+
### ドキュメント品質
75+
76+
- [ ] CLAUDE.md が最新
77+
- [ ] コミットメッセージが詳細
78+
- [ ] PR説明が包括的
79+
80+
### コミットメッセージ形式
81+
82+
**日本語でコミットメッセージを書く**（英単語が含まれても良い）
83+
84+
```
85+
feat: 簡潔で明確なタイトル
86+
87+
詳細な説明：
88+
- 何を実装したか
89+
- なぜその実装を選んだか
90+
- どのような影響があるか
91+
92+
🤖 Generated with [Claude Code](https://claude.ai/code)
93+
Co-Authored-By: Claude <[email protected]>
94+
```
95+
96+
---
97+
98+
## 今回の学び（2025-06-28）
99+
100+
### 実装: AI向けJSON出力機能
101+
102+
- **要件**: TypeScript GraphにAI連携用JSON出力機能を追加
103+
- **成果**: `--json`オプションによる構造化データ出力
104+
- **学習ポイント**:
105+
- stdout汚染防止の重要性（console.log削除）
106+
- 既存パターンとの整合性（CLI設計、出力方式）
107+
- 包括的テストの価値（integration test 4シナリオ）
108+
- DRY原則適用（重複関数呼び出し解消）
109+
110+
### プロセス改善
111+
112+
- **TodoWrite活用**: 7タスクの段階的管理
113+
- **Tool並列実行**: 効率的な情報収集
114+
- **段階的実装**: 小さなステップでの確実な進歩
115+
- **継続的テスト**: 変更の度の動作確認
116+
117+
このワークフローを他プロジェクトでも適用し、継続的に改善していく。

‎README.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@ npm install --global @ysk8hori/typescript-graph
8787
| `-w, --watch-metrics` | Monitors file changes in real-time and displays metrics such as Maintainability Index, Cyclomatic Complexity, and Cognitive Complexity whenever changes occur. Ideal for continuous quality monitoring. |
8888
| `--config-file` | Specify the relative path to the config file (from the current directory or as specified by -d, --dir). The default is .tsgrc.json. |
8989
| `--vue` (experimental) | `.vue` files are also included in the analysis. A temporary working directory is created using Node.js's `fs.mkdtempSync`, where all files targeted by `tsc` as well as `.vue` files are copied for processing. `.vue` files are renamed to `.vue.ts` unless a file with the same name already exists in the directory. |
90+
| `--stdout` | Output both dependency graph (Mermaid) and code metrics (JSON) to stdout. |
9091
| `-h, --help` | Display help for the command. |
9192

9293
## usage
@@ -501,3 +502,86 @@ The values in `()` represent the difference from when monitoring started. Improv
501502
| Maintainability Index | Higher |
502503
| Cyclomatic Complexity | Lower |
503504
| Cognitive Complexity | Lower |
505+
506+
## stdout Output: Structured Format for Tool and AI Integration
507+
508+
The `--stdout` option outputs a **machine-parsable format** that combines architectural structure and code complexity metrics.
509+
It’s designed for **AI agents like Claude Code or GitHub Copilot Agent**, as well as **humans who prefer structured command-line output**.
510+
511+
### `--stdout` Option
512+
513+
```bash
514+
tsg --stdout
515+
```
516+
517+
This produces two clearly separated sections:
518+
519+
1. **Dependency Graph (Mermaid)**
520+
A visual graph of file dependencies, useful for detecting circular references and architectural patterns.
521+
522+
2. **Code Metrics (JSON)**
523+
A machine-readable summary of key maintainability indicators for each file.
524+
525+
**Example output:**
526+
527+
```
528+
=== DEPENDENCY GRAPH ===
529+
flowchart
530+
[dependency relationships in Mermaid syntax]
531+
532+
=== CODE METRICS ===
533+
{
534+
"metadata": {...},
535+
"metrics": [
536+
{
537+
"filePath": "src/utils.ts",
538+
"maintainabilityIndex": 95.75,
539+
"cyclomaticComplexity": 1,
540+
"cognitiveComplexity": 0
541+
}
542+
]
543+
}
544+
```
545+
546+
### Why This Format?
547+
548+
- **Human-friendly + machine-friendly**
549+
Easily piped into LLM agents, static analyzers, or documentation tools. Humans can read it too.
550+
551+
- **Mermaid for structure**
552+
Enables visual recognition of circular dependencies, hub files, and architectural boundaries.
553+
554+
- **JSON for metrics**
555+
Clean structure for parsing, threshold checking, or automated prioritization.
556+
557+
- **Focused indicators**
558+
Only the three most relevant metrics:
559+
560+
- Maintainability Index
561+
- Cyclomatic Complexity
562+
- Cognitive Complexity
563+
564+
### Best Practices for External Integration
565+
566+
```bash
567+
# Target specific modules for AI refactoring
568+
tsg src/components --stdout --exclude test
569+
570+
# Generate an architectural map (excluding noise)
571+
tsg --stdout --abstraction node_modules --exclude test stories
572+
573+
# Highlight known complex areas for review
574+
tsg --stdout --highlight problematic-file.ts --exclude utils
575+
```
576+
577+
You can redirect the output for post-processing:
578+
579+
```bash
580+
tsg --stdout > graph-and-metrics.txt
581+
```
582+
583+
Or feed it directly into tools:
584+
585+
```bash
586+
tsg --stdout | some-ai-agent --analyze
587+
```

‎docs/README_en.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@ npm install --global @ysk8hori/typescript-graph
8787
| `-w, --watch-metrics` | Monitors file changes in real-time and displays metrics such as Maintainability Index, Cyclomatic Complexity, and Cognitive Complexity whenever changes occur. Ideal for continuous quality monitoring. |
8888
| `--config-file` | Specify the relative path to the config file (from the current directory or as specified by -d, --dir). The default is .tsgrc.json. |
8989
| `--vue` (experimental) | `.vue` files are also included in the analysis. A temporary working directory is created using Node.js's `fs.mkdtempSync`, where all files targeted by `tsc` as well as `.vue` files are copied for processing. `.vue` files are renamed to `.vue.ts` unless a file with the same name already exists in the directory. |
90+
| `--stdout` | Output both dependency graph (Mermaid) and code metrics (JSON) to stdout. |
9091
| `-h, --help` | Display help for the command. |
9192

9293
## usage
@@ -501,3 +502,86 @@ The values in `()` represent the difference from when monitoring started. Improv
501502
| Maintainability Index | Higher |
502503
| Cyclomatic Complexity | Lower |
503504
| Cognitive Complexity | Lower |
505+
506+
## stdout Output: Structured Format for Tool and AI Integration
507+
508+
The `--stdout` option outputs a **machine-parsable format** that combines architectural structure and code complexity metrics.
509+
It's designed for **AI agents like Claude Code or GitHub Copilot Agent**, as well as **humans who prefer structured command-line output**.
510+
511+
### `--stdout` Option
512+
513+
```bash
514+
tsg --stdout
515+
```
516+
517+
This produces two clearly separated sections:
518+
519+
1. **Dependency Graph (Mermaid)**
520+
A visual graph of file dependencies, useful for detecting circular references and architectural patterns.
521+
522+
2. **Code Metrics (JSON)**
523+
A machine-readable summary of key maintainability indicators for each file.
524+
525+
**Example output:**
526+
527+
```
528+
=== DEPENDENCY GRAPH ===
529+
flowchart
530+
[dependency relationships in Mermaid syntax]
531+
532+
=== CODE METRICS ===
533+
{
534+
"metadata": {...},
535+
"metrics": [
536+
{
537+
"filePath": "src/utils.ts",
538+
"maintainabilityIndex": 95.75,
539+
"cyclomaticComplexity": 1,
540+
"cognitiveComplexity": 0
541+
}
542+
]
543+
}
544+
```
545+
546+
### Why This Format?
547+
548+
- **Human-friendly + machine-friendly**
549+
Easily piped into LLM agents, static analyzers, or documentation tools. Humans can read it too.
550+
551+
- **Mermaid for structure**
552+
Enables visual recognition of circular dependencies, hub files, and architectural boundaries.
553+
554+
- **JSON for metrics**
555+
Clean structure for parsing, threshold checking, or automated prioritization.
556+
557+
- **Focused indicators**
558+
Only the three most relevant metrics:
559+
560+
- Maintainability Index
561+
- Cyclomatic Complexity
562+
- Cognitive Complexity
563+
564+
### Best Practices for External Integration
565+
566+
```bash
567+
# Target specific modules for AI refactoring
568+
tsg src/components --stdout --exclude test
569+
570+
# Generate an architectural map (excluding noise)
571+
tsg --stdout --abstraction node_modules --exclude test stories
572+
573+
# Highlight known complex areas for review
574+
tsg --stdout --highlight problematic-file.ts --exclude utils
575+
```
576+
577+
You can redirect the output for post-processing:
578+
579+
```bash
580+
tsg --stdout > graph-and-metrics.txt
581+
```
582+
583+
Or feed it directly into tools:
584+
585+
```bash
586+
tsg --stdout | some-ai-agent --analyze
587+
```

0 commit comments

Comments
 (0)