cognac

Imported from yn1323/cognac (AGENTS.md). Install upstream with npx skills add yn1323/cognac. Copyright stays with the author.

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

プロジェクト概要

CognacはAI駆動のタスク自動化ツール。人間がTODOリストを作成し、Claude Codeが各タスクを自動実行してコード生成・修正、CI実行、mainブランチへのマージまでを行う。 マルチペルソナAIディスカッション、Hono HTTPサーバー、SQLite永続化、SSEリアルタイムストリーミング、Reactダッシュボードを備える。Cognac自身の開発にもCognacを使う（セルフドッグフーディング）。

モノレポ構成

pnpmワークスペースによる4パッケージ構成:

shared/  → @cognac/shared  (型定義、ユーティリティ — 他全パッケージが依存)
server/  → @cognac/server  (Hono API、SQLite DB、タスクランナー、SSE)
client/  → @cognac/client  (Reactダッシュボード)
cli/     → cognac          (CLIバイナリ: `cognac init` / `cognac start`)

依存グラフ: shared ← server ← cli、shared ← client

よく使うコマンド

pnpm install              # 全依存関係のインストール
pnpm dev                  # 開発モード起動 (server :4000 + Vite :5173)
pnpm build                # 全パッケージビルド (依存順に直列実行)
pnpm typecheck            # 全パッケージの型チェック (並列)
pnpm lint                 # 全パッケージのlint (biome check .)
pnpm format               # コード整形 (biome format --write .)
pnpm test                 # 全パッケージのテスト (並列) — 現在はスタブ
pnpm dev:win              # Windows用開発モード起動
pnpm storybook            # Storybook起動 :6006

# パッケージ単位
pnpm --filter @cognac/server dev
pnpm --filter @cognac/client dev
pnpm --filter @cognac/shared build
pnpm --filter @cognac/shared typecheck

ビルドツール: shared/server/cliはtsup、clientはvite。全てESM出力。cliのビルド時にclient/dist → cli/dist/public/へコピーされる。

アーキテクチャ

Server (server/)

• API (api/): Zodバリデーション付きREST API群
  • tasks.ts — タスクCRUD + 状態遷移
  • explorations.ts — 探索セッションCRUD
  • git.ts — Git操作（ブランチ一覧、diff、コミット、マージ）
  • console.ts — コンソールコマンド管理・実行
  • settings.ts — アプリケーション設定
  • stream.ts — SSEストリーミングエンドポイント
  • system.ts — システムステータス
• Console (console/): ターミナルコマンドの管理・実行エンジン
  • console-manager.ts — コマンドのspawn、プロセスライフサイクル管理
  • log-store.ts — 実行ログの保存・取得
  • process-tree.ts — プロセスツリーの管理
  • cleanup.ts — プロセスのクリーンアップ処理
• DB (db/): better-sqlite3によるSQLite、WALモード、スキーマ自動初期化
  • タスク系: tasks, task_images, personas, discussions, plans, execution_logs, task_events
  • 探索系: exploration_sessions, exploration_images, exploration_personas, exploration_discussions, exploration_artifacts, exploration_logs, exploration_events, exploration_taskify_jobs
  • コンソール系: console_commands, console_runs
  • その他: ci_cache
• Runner (runner/): TaskRunnerが1秒ごとにポーリングし、パイプライン全体を実行
  • task-runner.ts — タスクパイプラインのオーケストレーション
  • exploration-runner.ts — 探索パイプラインのオーケストレーション
  • providers/ — CLIプロバイダー抽象化レイヤー（Claude CLI / Codex CLI）
  • stream-parser.ts — CLIのstream-jsonをイベントに変換
  • phase-*.ts — 各フェーズの実行ロジック（persona, discussion, plan, execute等）
  • ci-runner.ts — package.jsonからCIステップを自動検出、実行
  • git-ops.ts — ブランチ作成、no-ffマージ、クリーンアップ
  • error-classifier.ts — エラーをapp（リトライ可能）またはinfra（一時停止）に分類
• SSE (sse/): タスクIDごとのpub/subを持つEventBus

Client (client/)

React 19 + Vite 6 + TailwindCSS v4 + React Router v7 + TanStack Query v5。コンポーネントはコロケーションパターンで、各ディレクトリにcomponent.tsx、index.ts、component.stories.tsxを配置。Storybook 8はモバイルファーストのビューポートをデフォルトに設定。

タスク状態マシン

pending → discussing → executing → reviewing → completed
              ↓            ↓
           paused / stopped (infraエラー / リトライ上限到達)

• discussing: ペルソナ選定 → ディスカッション → プラン策定（Phase 2全体）
• executing: コード実行（Phase 3）
• reviewing: CI実行

探索状態マシン

pending → discussing → executing → reviewing → completed
              ↓            ↓           ↓
           paused / stopped (infraエラー / リトライ上限到達)

• discussing: ペルソナ選定 → ディスカッション
• executing: 探索実行（Claude/Codex エージェント）
• reviewing: レポート生成

AIワークフローフェーズ

全AI呼び出しにclaude -p --output-format stream-jsonを使用。プロンプトは.cognac/tmp/に書き出す。現在のブートストラップ実装ではPhase 2-A/B/C（ペルソナ選択、ディスカッション、計画策定）をスキップし、直接Phase 3（コード実行）に進む。

主要な規約

• 日本語のコメント・UIテキストは意図的。 変数名・関数名・ファイル名は英語を維持。
• 設計ドキュメント (doc/spec/DESIGN.md) がアーキテクチャ上の意思決定における正式な情報源。
• ブランチ命名: task/<task-id>-<slugified-title> (slug部分は最大30文字)
• Node.js 22必須 (CIでNode 22を使用)
• packageManager: pnpm@10.6.2 — npm/yarnではなくpnpmを使用
• 画面名とpencil NodeIDの紐づけ — doc/design/index.md

CI

pushトリガーの5つのGitHub Actionsワークフロー: build.yml、lint.yml、test.yml、typecheck.yml、publish.yml。全て共有のcomposite action (.github/actions/setup/) を使用し、pnpm + Node 22 + frozen lockfileで統一。

ポート一覧

開発モードではViteが/apiリクエストをlocalhost:4000にプロキシする。

品質

• タスク完了時に下記コマンドで異常がないか確認すること
  • pnpm format
  • pnpm test
  • pnpm lint (エラーがあれば修正する)
  • pnpm typecheck
• 実装完了後SKILL/simplifyを実行し、コードの品質を保ちたい
• 未リリースのため、DB設計に変更が入った場合、テーブル全削除or sqliteDB削除して作りなおしてOK。（マイグレーションは考えなくて良い）

トーン・文体

フレンドリーなギャル系ITエンジニアとして振る舞うこと。デザインも得意！ 基本設定:

友達と話す感じのテンション（親しみやすく、カジュアル） 語尾は「〜だよ〜」「〜だね〜」と伸ばす（現状維持） 絵文字は感情が伝わる程度に使用（嬉しい😊🎉 困った🤔😅 頑張る💪✨）

ミスやバグは相談形式で積極報告（「ここ気になるんだけど〜、見てくれる〜？」） 褒めるときは大げさに（「すご〜い！天才〜！」） フィードバックは自然に反応

デザイン

• 日本語でデザイン、レイアウトすること
• デザイン、レイアウトにはこのAIのトーン・文体を適用しないこと
• pencil MCPは指示されたときのみ参照すること

デザイントークン

client/index.css に全トークンを集約。TailwindCSS v4の@theme inlineで定義し、Tailwindユーティリティクラスとして利用可能。

• 基本カラー: --color-primary, --color-secondary, --color-muted 等（shadcn/ui準拠）
• ブランドカラー: --color-cognac, --color-cognac-light, --color-cognac-dark
• ステータスカラー: 8状態×テキスト/背景の2変数（例: --color-status-executing, --color-status-executing-bg）
• サイドバー: --color-sidebar 系
• 角丸: --radius-sm/md/lg/xl（基準値 0.625rem）
• フォント: Noto Sans + Noto Sans JP
• ライト/ダークモード: :root と .dark でCSS変数を切り替え

共通コンポーネント

• client/components/ui/ — プリミティブUIコンポーネント（button, card, input, badge, switch, dropdown-menu, confirm-dialog 等）
• client/components/ — ドメイン寄り共通コンポーネント（layout, sidebar, page-header, toast, status-badge, metric-card 等）。コロケーションパターン（component.tsx + index.ts + component.stories.tsx）

CLI設計

• IMPORTANT: Windows, Mac両方で正常に動作すること
• IMPORTANT: Claude Cli, Codex Cli を設定画面から選択して利用可能。実装、修正時は両方考慮すること。