Standardizing Dev Workflow

Quick Start

aqua経由でtaskとlefthookを導入し、標準開発フローを構築する。

# 1. aqua初期化（なければ）
aqua init

# 2. task, lefthookを追加
aqua g -i go-task/task evilmartians/lefthook

# 3. インストール
aqua install

# 4. Taskfile初期化
task --init

# 5. lefthook初期化
lefthook install

Key Concepts

aqua: CLIツールのバージョン管理。プロジェクトごとにツールを固定
task: YAMLベースのタスクランナー。Makefileの代替
lefthook: 高速なGitフックマネージャー。pre-commit/pre-pushを管理
includes: モノレポで複数Taskfileを連携
標準フロー: format（pre-commit）→ lint（pre-push）

Workflows

Workflow 1: 初期セットアップ

# aqua.yml
registries:
  - type: standard
    ref: v4.250.0

packages:
  - name: go-task/task@v3
  - name: evilmartians/lefthook@v1

# Taskfile.yml
version: '3'

tasks:
  format:
    desc: Format code
    cmds:
      - prettier --write .

  lint:
    desc: Lint code
    cmds:
      - eslint .

  hooks:install:
    desc: Install git hooks
    cmds:
      - lefthook install

# lefthook.yml
pre-commit:
  parallel: true
  commands:
    format:
      run: task format
      stage_fixed: true

pre-push:
  commands:
    lint:
      run: task lint

Workflow 2: タスク追加

# Taskfile.yml に追加
tasks:
  build:
    desc: Build the project
    cmds:
      - go build -o bin/app .

  test:
    desc: Run tests
    cmds:
      - go test ./...

  dev:
    desc: Run development server
    deps: [build]
    cmds:
      - ./bin/app serve

Workflow 3: モノレポ対応

# ルートのTaskfile.yml
version: '3'

includes:
  backend:
    taskfile: ./backend/Taskfile.yml
    dir: ./backend
  frontend:
    taskfile: ./frontend/Taskfile.yml
    dir: ./frontend
  shared:
    taskfile: ./shared/Taskfile.yml
    dir: ./shared
    optional: true

tasks:
  all:build:
    desc: Build all projects
    cmds:
      - task: backend:build
      - task: frontend:build

  all:lint:
    desc: Lint all projects
    cmds:
      - task: backend:lint
      - task: frontend:lint

呼び出し例:

task backend:build - backendのbuildタスク
task frontend:dev - frontendのdevタスク
task all:build - 全プロジェクトのビルド

Workflow 4: 既存リポジトリの監査

以下をチェックし、ガイドライン逸脱があれば修正提案する:

監査チェックリスト:

[ ] aqua.ymlが存在するか
[ ] Taskfile.ymlが存在するか
[ ] lefthook.ymlが存在するか
[ ] format/lintタスクが定義されているか
[ ] README/CLAUDE.mdに直接コマンド（npm run, python -m等）がないか
[ ] package.json scriptsがtask経由になっているか
[ ] Makefileがtask経由になっているか
[ ] .github/workflows内がtask経由になっているか

Examples

Example 1: README.mdの直接コマンドを修正

Before:

## Development
npm run lint
npm run format
npm test

After:

## Development
task lint
task format
task test

Example 2: package.jsonからTaskfileへ移行

Before (package.json):

{
  "scripts": {
    "lint": "eslint .",
    "format": "prettier --write .",
    "test": "jest"
  }
}

After (Taskfile.yml):

version: '3'

tasks:
  lint:
    desc: Lint code
    cmds:
      - npx eslint .

  format:
    desc: Format code
    cmds:
      - npx prettier --write .

  test:
    desc: Run tests
    cmds:
      - npx jest

Example 3: CI/CDをtask経由に変更

Before (.github/workflows/ci.yml):

- run: npm run lint
- run: npm test

After:

- run: aqua install
- run: task lint
- run: task test

includeオプション一覧

| オプション | 説明 | |-----------|------| | taskfile | サブTaskfileのパス | | dir | タスク実行時の作業ディレクトリ（必須） | | optional: true | Taskfileがなくてもエラーにしない | | aliases | namespaceの別名（例: [api]） | | vars | サブTaskfileへの変数渡し | | flatten: true | namespaceなしで呼び出し可能 |

Error Handling

taskコマンドが見つからない:

export PATH="${AQUA_ROOT_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/aquaproj-aqua}/bin:$PATH"
aqua install

lefthookが動作しない:

lefthook install  # hookを再インストール

Taskfile構文エラー:

task --list  # エラーがあれば表示される

standardizing-dev-workflow