mako-flow

Linear-integrated AI centric workflow management tool
Category: discovered
Tags: github, community
Version: 1.0.0
Author: walid
Downloads: 0
Updated: 2025-11-22
Source: chronista-club/fleetflow
Download the latest version (v1.0.0) from this page.
SKILL.md

# Mako Flow Skill

仕様策定→設計→コーディングを段階的に進めるためのワークフロースキル

## コンセプト

1. **Hearing First（ヒアリングファースト）**: まず要件を丁寧にヒアリング
2. **Spec Design（仕様設計）**: specディレクトリで仕様を整理
3. **Design Phase（設計フェーズ）**: designディレクトリで技術設計
4. **Coding（コーディング）**: コードに落とし込む

## フェーズ

### Phase 1: Hearing（ヒアリング）

ユーザーの要件を段階的にヒアリングします。

**質問の観点:**
- 何を作りたいのか？（What）
- なぜ必要なのか？（Why）
- どう使われるのか？（How）
- 誰が使うのか？（Who）
- いつ必要なのか？（When）

**成果物:**
- ヒアリング結果のメモ
- ユースケースの明確化

### Phase 2: Spec（仕様策定）

`spec/` ディレクトリに仕様を整理します。

**ディレクトリ構造:**
```
spec/
├── XX-feature-name/
│   ├── SPEC.md          # 機能仕様
│   ├── USE_CASES.md     # ユースケース
│   └── REQUIREMENTS.md  # 要件定義
└── INDEX.md             # 全仕様の索引
```

**SPEC.mdの構成:**
- **概要**: 機能の目的と背景
- **要件**: 機能要件と非機能要件
- **仕様**: 詳細な仕様
- **制約**: 技術的制約やビジネス制約
- **成功基準**: 受け入れ条件

### Phase 3: Design（設計）

`design/` ディレクトリに技術設計を記述します。

**ディレクトリ構造:**
```
design/
├── XX-feature-name/
│   ├── DESIGN.md        # アーキテクチャ設計
│   ├── API.md           # API設計
│   ├── DATA_MODEL.md    # データモデル
│   └── FLOW.md          # 処理フロー
└── INDEX.md             # 全設計の索引
```

**DESIGN.mdの構成:**
- **アーキテクチャ**: システム構成
- **技術選定**: 使用技術と選定理由
- **データ構造**: 型定義、スキーマ
- **処理フロー**: フローチャート、シーケンス図
- **エラーハンドリング**: エラー処理方針

### Phase 4: Coding（コーディング）

設計に基づいてコーディングします。

**コーディングの進め方:**
1. **型定義から**: データ構造を先に定義
2. **インターフェース**: 公開APIを先に設計
3. **テストファースト**: テストを書いてから実装
4. **段階的実装**: 小さく分割して実装

**確認事項:**
- [ ] 仕様通りに動作するか
- [ ] テストが通るか
- [ ] ドキュメントが更新されているか
- [ ] エラーハンドリングが適切か

## ヒアリング手法

### 1. オープンクエスチョン

まず広く聞く：
- 「どんな機能が欲しいですか？」
- 「どんな課題を解決したいですか？」
- 「理想的な使い方を教えてください」

### 2. クローズドクエスチョン

具体化する：
- 「この機能は必須ですか、それとも任意ですか？」
- 「優先度は高いですか？」
- 「既存の○○と似ていますか？」

### 3. 一問一答方式（推奨）

複数の質問を一度にせず、リストを作成して一つずつ確認する：

**❌ 避けるべき:**
```
質問1: Aについてどうしますか？
質問2: Bについてどうしますか？
質問3: Cについてどうしますか？
```
→ 回答しづらい、漏れが発生しやすい

**✅ 推奨:**
```
確認事項リスト（3つあります）

## 質問1/3: Aについて
[具体的な選択肢を提示]

回答を待つ → 次の質問へ
```

**メリット:**
- 回答しやすい
- 意思決定に集中できる
- 確実に全ての質問に答えられる
- 進捗が明確（1/3, 2/3...）

### 3. 5W1H

詳細を明確にする：
- **What**: 何を実現するか
- **Why**: なぜ必要か
- **Who**: 誰が使うか
- **When**: いつ使うか
- **Where**: どこで使うか
- **How**: どう実装するか

### 4. 制約の確認

技術的・ビジネス的制約：
- 「パフォーマンス要件はありますか？」
- 「セキュリティ要件はありますか？」
- 「既存システムとの互換性は必要ですか？」

## テンプレート

### ヒアリングシート

```markdown
# ヒアリングシート: [機能名]

## 日時
- 2025-XX-XX

## 参加者
- [名前]

## 背景・目的
[なぜこの機能が必要か]

## 現状の課題
[現在困っていること]

## 要望
[実現したいこと]

## ユースケース
1. [ユースケース1]
2. [ユースケース2]

## 優先度
- [ ] 必須
- [ ] 重要
- [ ] あると良い

## 制約
[技術的・ビジネス的制約]

## 疑問点
[確認が必要なこと]

## Next Actions
- [ ] [アクション1]
- [ ] [アクション2]
```

### SPEC.md テンプレート

```markdown
# [機能名] 仕様

## 概要
[機能の目的と背景]

## 要件

### 機能要件
1. [要件1]
2. [要件2]

### 非機能要件
- **パフォーマンス**: [要件]
- **セキュリティ**: [要件]
- **可用性**: [要件]

## 仕様

### 基本仕様
[詳細な仕様]

### 入出力
- **入力**: [入力仕様]
- **出力**: [出力仕様]

## 制約
- [制約1]
- [制約2]

## 成功基準
- [ ] [基準1]
- [ ] [基準2]
```

### DESIGN.md テンプレート

```markdown
# [機能名] 設計

## アーキテクチャ
[システム構成図]

## 技術選定
- **言語**: [選定理由]
- **フレームワーク**: [選定理由]
- **ライブラリ**: [選定理由]

## データ構造

### 型定義
\`\`\`rust
struct Example {
    field: Type,
}
\`\`\`

## 処理フロー
[フローチャートまたはシーケンス図]

## API設計
[API仕様]

## エラーハンドリング
[エラー処理方針]

## テスト戦略
[テスト方針]
```

## 使用例

### 例: 新機能の開発

```bash
# Phase 1: ヒアリング
「flow watch機能を追加したいです」

→ ヒアリング開始
  - どんなファイルを監視しますか？
  - 変更時に何をしますか？
  - 既存のツールとの違いは？

# Phase 2: 仕様策定
spec/07-watch-command/SPEC.md を作成

# Phase 3: 設計
design/07-watch-command/DESIGN.md を作成

# Phase 4: コーディング
コードを実装
```

## ベストプラクティス

### ヒアリング時
- 仮定せず、必ず確認する
- ユーザーの言葉で理解する
- 曖昧な部分は具体例で確認
- 優先順位を明確にする

### 仕様策定時
- 簡潔で明確に書く
- 具体例を入れる
- 境界条件を明記
- レビュー可能な粒度にする

### 設計時
- シンプルから始める
- 拡張性を考慮
- 既存パターンを活用
- トレードオフを明記

### コーディング時
- 小さく分割
- テストファースト
- ドキュメント同期
- レビューしやすいコミット

## 参考資料

- spec-design-guide skill
- hearing-first skill
- 既存のspec/ディレクトリ
- 既存のdesign/ディレクトリ