takt/AGENTS.md

Repository Guidelines

このリポジトリに貢献する際の基本的な構成と期待値をまとめています。短い説明と例で各セクションを完結に示します。

プロジェクト構成とモジュール整理

• 主要ソースは src/ にあり、エントリポイントは src/index.ts、CLI は src/cli.ts です。
• テストは src/__tests__/ に置き、ファイル名は対象機能が一目でわかるようにします（例: client.test.ts）。
• ビルド成果物は dist/、実行スクリプトは bin/、静的リソースは resources/、ドキュメントは docs/ で管理します。
• 設定やキャッシュを使う際は ~/.takt/ 以下（実行時）や .takt/（プロジェクト固有）を参照します。

ビルド・テスト・開発コマンド

npm run build       # TypeScript コンパイルを実行し dist/ を生成
npm run watch       # ソース変更を監視しつつ再ビルド
npm run lint        # ESLint で src/ を解析
npm run test        # Vitest で全テストを実行
npm run test:watch  # テスト実行をウォッチ

• 単体テストを個別実行する例: npx vitest run src/__tests__/client.test.ts。

コーディングスタイルと命名

• TypeScript + strict モードを前提にし、可読性や null 安全を優先します。
• ESM 形式なので import の拡張子は .js に固定してください。
• ESLint（eslint src/）と prettier ルールを守り、命名は camelCase（関数・変数）および PascalCase（クラス）を採用。
• クロスファイルの共有型は src/types/ 風に整理し、既存の命名パターンを踏襲します。

テスト指針

• テストフレームワークは Vitest（vitest.config.ts 参照）。全ての新機能・修正には関連テストを追加。
• テストファイル名は <対象>.test.ts、あるいは <対象>.spec.ts で統一。
• コンポーネント依存はモックやスタブを使い、状態を分離したシナリオを心がけます。

コミットとプルリク

• 履歴は「短い要約 + 1 行」スタイル。英語・日本語混在可、目的が伝わるよう feat:, fix: 等のプレフィックスも可。
• PR には変更概要・テスト結果・関連 Issue（あれば）を含め、小さな対象に絞ってレビュー負荷を抑えます。
• ドキュメントや設定変更を伴う場合は CHANGELOG.md への追記を検討し、スクリーンショットやログがあれば添付します。

セキュリティと設定の注意

• 脆弱性は公開 Issue ではなくメンテナへ直接報告します。
• .takt/logs/ など機密情報を含む可能性のあるファイルは共有しないでください。
• ~/.takt/config.yaml の trusted ディレクトリは最小限にし、不要なパスは登録しないでください。
• 新しいワークフローを追加する場合は ~/.takt/workflows/ の既存スキーマを踏襲し、不要な拡張を避けます。