From 3df872d746b2eb63b2d593592df43e690f7d2053 Mon Sep 17 00:00:00 2001 From: keitakn Date: Sat, 28 Mar 2026 19:52:37 +0900 Subject: [PATCH 1/5] =?UTF-8?q?#1=20=E3=83=97=E3=83=AD=E3=82=B8=E3=82=A7?= =?UTF-8?q?=E3=82=AF=E3=83=88=E3=81=AE=E5=88=9D=E6=9C=9F=E9=96=8B=E7=99=BA?= =?UTF-8?q?=E7=92=B0=E5=A2=83=E3=82=92=E3=82=BB=E3=83=83=E3=83=88=E3=82=A2?= =?UTF-8?q?=E3=83=83=E3=83=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit TypeScript, Vitest, ultracite (Biome), Prettierを導入し、 CLIツールとしてのpackage.json設定、tsconfig.json、各種設定ファイル、 CLAUDE.md、README.md、PRテンプレートを追加。 Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/PULL_REQUEST_TEMPLATE.md | 49 + .github/mcp-servers.json | 8 + .github/workflows/ci.yml | 36 + .gitignore | 7 +- .npmrc | 2 + .prettierignore | 1 + CLAUDE.md | 93 ++ README.md | 47 + biome.jsonc | 6 + docs/basic-coding-guidelines.md | 126 +++ package-lock.json | 1668 ++++++++++++++++++++++++++++++ package.json | 38 + src/bin/planloop.ts | 7 + tsconfig.json | 19 + vitest.config.ts | 13 + 15 files changed, 2119 insertions(+), 1 deletion(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/mcp-servers.json create mode 100644 .github/workflows/ci.yml create mode 100644 .npmrc create mode 100644 .prettierignore create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100644 biome.jsonc create mode 100644 docs/basic-coding-guidelines.md create mode 100644 package-lock.json create mode 100644 package.json create mode 100644 src/bin/planloop.ts create mode 100644 tsconfig.json create mode 100644 vitest.config.ts diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..236594a --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,49 @@ + + + + +# issueURL + + + +# この PR で対応する範囲 / この PR で対応しない範囲 + + + +# 変更点概要 + + + +# レビュアーに重点的にチェックして欲しい点 + + + +# 補足情報 + + diff --git a/.github/mcp-servers.json b/.github/mcp-servers.json new file mode 100644 index 0000000..d39c47e --- /dev/null +++ b/.github/mcp-servers.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "lgtmeow": { + "type": "sse", + "url": "https://api.lgtmeow.com/sse" + } + } +} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..9dff751 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,36 @@ +name: ci + +on: + workflow_dispatch: + push: + branches: + - "**" + +jobs: + build: + name: Build And Test + runs-on: ubuntu-latest + timeout-minutes: 5 + strategy: + matrix: + node-version: [24.x] + steps: + - uses: actions/checkout@v6 + - name: Use Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v6 + with: + node-version: ${{ matrix.node-version }} + cache: npm + + - name: Install dependencies + run: npm ci + + - name: Lint and Test + run: | + npm run lint + npm run build + npm run test:ci + env: + GOOGLE_GENERATIVE_AI_API_KEY: ${{ secrets.GOOGLE_GENERATIVE_AI_API_KEY }} + TURSO_DATABASE_URL: ${{ secrets.TURSO_DATABASE_URL }} + TURSO_AUTH_TOKEN: ${{ secrets.TURSO_AUTH_TOKEN }} diff --git a/.gitignore b/.gitignore index 9a5aced..82376a7 100644 --- a/.gitignore +++ b/.gitignore @@ -78,9 +78,11 @@ web_modules/ .next out +# Build output +dist + # Nuxt.js build / generate output .nuxt -dist # Gatsby files .cache/ @@ -137,3 +139,6 @@ dist # Vite logs files vite.config.js.timestamp-* vite.config.ts.timestamp-* + +# MCP +.mcp.json diff --git a/.npmrc b/.npmrc new file mode 100644 index 0000000..3787a26 --- /dev/null +++ b/.npmrc @@ -0,0 +1,2 @@ +legacy-peer-deps=true +save-exact=true diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..6e5aea8 --- /dev/null +++ b/.prettierignore @@ -0,0 +1 @@ +.serena/ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d18f471 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,93 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +@nekochans/planloop is a Node.js CLI tool (installed via `npm install -g`) that reviews implementation plans created by AI coding agents using other AI agents to drive quality improvement loops. Written in TypeScript with ESM (`"type": "module"`). + +## Commands + +```bash +npm run build # TypeScript build (tsc) +npm test # Run all tests (vitest run) +npx vitest run src/path/to/file.test.ts # Run a single test file +npm run lint # Biome (ultracite) + Prettier check +npm run format # Biome (ultracite) + Prettier auto-fix +``` + +## Architecture + +- **Entry point**: `src/bin/planloop.ts` — CLI entry with shebang, mapped to `planloop` command via `bin` in package.json +- **Build output**: `dist/` (compiled from `src/` by tsc, git-ignored) +- **Module system**: ESM (Node16 module resolution) + +## Lint / Format Strategy + +- `.ts` files → ultracite (Biome) handles both linting and formatting +- `.yaml`, `.yml`, `.md`, `.mdx` → Prettier handles formatting +- Biome config extends `ultracite/biome/core` (see `biome.jsonc`) + +## Dependency Management + +- `.npmrc` enforces `save-exact=true` — all dependency versions must be pinned without `^` or `~` prefixes +- Use `npm install` (not yarn/pnpm) + +## 関連ドキュメント + +### **重要: 基本的なコーディングガイドライン** + +必ず以下のドキュメントを参照してから開発を開始してください: + +@docs/basic-coding-guidelines.md + +## 品質管理 + +全ての開発タスク完了時に、以下の手順を順番に実施してください。1つでも異常終了した場合は、問題点を修正してエラーが出なくなるまで修正を繰り返してください。 + +1. `npm run format` — Formatterの適用 +2. `npm run lint` — Linterエラーがないことを確認 +3. `npm run test` — テストコードの実行 +4. `npm run build` — ビルドが正常終了することを確認 + +## GitとGitHubワークフロールール + +### GitHubの利用ルール + +`gh` コマンドを利用してGitHubへのPRを作成する事が可能です。 + +許可されている操作は以下の通りです。 + +- GitHubへのPRの作成 +- GitHubへのPRへのコメントの追加 +- GitHub Issueの新規作成 +- GitHub Issueへのコメントの追加 + +**以下の操作はユーザーの許可があれば可能です。** + +- Gitへのコミット +- GitHubへのプッシュ + +### コミットメッセージの作成ルール + +- 対応issueがある場合は、コミットメッセージに `#` を記載します + +### PR作成ルール + +- ブランチはユーザーが作成しますので現在のブランチをそのまま利用します +- PRのタイトルは日本語で入力します +- PRの作成先は特別な指示がない場合は `main` ブランチになります +- PRの説明欄は @.github/PULL_REQUEST_TEMPLATE.md を参考に入力します +- 対応issueがある場合は、PRの説明欄に `#` を記載します +- Issue番号は現在のブランチ名から取得出来ます、例えば `feature/issue7/add-docs` の場合は `7` がIssue番号になります +- PRの説明欄には主に以下の情報を含めてください + +#### PRの説明欄に含めるべき情報 + +- 変更内容の詳細説明よりも、なぜその変更が必要なのかを重視 +- 他に影響を受ける機能やAPIエンドポイントがあれば明記 + +#### 以下の情報はPRの説明欄に記載する事を禁止する + +- 1つのissueで1つのPRとは限らないので `fix #issue番号` や `close #issue番号` のようなコメントは禁止します +- 全てのテストをパス、Linter、型チェックを通過などのコメント（テストやCIが通過しているのは当たり前でわざわざ書くべき事ではない） diff --git a/README.md b/README.md new file mode 100644 index 0000000..4673f04 --- /dev/null +++ b/README.md @@ -0,0 +1,47 @@ +# @nekochans/planloop + +AI コーディングエージェントが作成した実装計画を他の AI エージェントでレビューを行い、品質改善のループを回す為のツールです。 + +## 必須環境 + +- Node.js >= 22 + +## セットアップ + +```bash +npm install +``` + +## 開発コマンド + +```bash +# ビルド +npm run build + +# テスト +npm test + +# Lint (Biome + Prettier) +npm run lint + +# Format (Biome + Prettier) +npm run format +``` + +## Lint / Format の方針 + +- `.ts` ファイル → [ultracite](https://www.ultracite.ai/) (Biome) で lint & format +- `.yaml` `.yml` `.md` `.mdx` → [Prettier](https://prettier.io/) で format + +## ディレクトリ構成 + +``` +src/ + bin/ + planloop.ts # CLI エントリポイント +dist/ # ビルド出力 (git 管理外) +``` + +## ライセンス + +MIT diff --git a/biome.jsonc b/biome.jsonc new file mode 100644 index 0000000..89069d9 --- /dev/null +++ b/biome.jsonc @@ -0,0 +1,6 @@ +{ + "$schema": "./node_modules/@biomejs/biome/configuration_schema.json", + "extends": [ + "ultracite/biome/core" + ] +} \ No newline at end of file diff --git a/docs/basic-coding-guidelines.md b/docs/basic-coding-guidelines.md new file mode 100644 index 0000000..589f1f2 --- /dev/null +++ b/docs/basic-coding-guidelines.md @@ -0,0 +1,126 @@ +# Basic Coding Guidelines(Provided by Ultracite) + +This project uses **Ultracite**, a zero-config preset that enforces strict code quality standards through automated formatting and linting. + +## Quick Reference + +- **Format code**: `npm exec -- ultracite fix` +- **Check for issues**: `npm exec -- ultracite check` +- **Diagnose setup**: `npm exec -- ultracite doctor` + +Biome (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable. + +--- + +## Core Principles + +Write code that is **accessible, performant, type-safe, and maintainable**. Focus on clarity and explicit intent over brevity. + +### Type Safety & Explicitness + +- Use explicit types for function parameters and return values when they enhance clarity +- Prefer `unknown` over `any` when the type is genuinely unknown +- Use const assertions (`as const`) for immutable values and literal types +- Leverage TypeScript's type narrowing instead of type assertions +- Use meaningful variable names instead of magic numbers - extract constants with descriptive names + +### Modern JavaScript/TypeScript + +- Use arrow functions for callbacks and short functions +- Prefer `for...of` loops over `.forEach()` and indexed `for` loops +- Use optional chaining (`?.`) and nullish coalescing (`??`) for safer property access +- Prefer template literals over string concatenation +- Use destructuring for object and array assignments +- Use `const` by default, `let` only when reassignment is needed, never `var` + +### Async & Promises + +- Always `await` promises in async functions - don't forget to use the return value +- Use `async/await` syntax instead of promise chains for better readability +- Handle errors appropriately in async code with try-catch blocks +- Don't use async functions as Promise executors + +### React & JSX + +- Use function components over class components +- Call hooks at the top level only, never conditionally +- Specify all dependencies in hook dependency arrays correctly +- Use the `key` prop for elements in iterables (prefer unique IDs over array indices) +- Nest children between opening and closing tags instead of passing as props +- Don't define components inside other components +- Use semantic HTML and ARIA attributes for accessibility: + - Provide meaningful alt text for images + - Use proper heading hierarchy + - Add labels for form inputs + - Include keyboard event handlers alongside mouse events + - Use semantic elements (`