specpack

specpack

AI コーディングエージェントが読み込むファイル（CLAUDE.md、AGENTS.md、.cursorrules、 Cursor ルール）を検査して生成し、プロジェクトの説明から完全なビルド仕様書を作成します。CLI、ライブラリ、MCP サーバーです。

npx specpack audit          # bloat score for the agent files in this repo (offline)
npx specpack init           # write a lean AGENTS.md from your manifests (offline)
npx specpack spec --describe "Booking app for dog groomers with deposits and SMS reminders"

CLAUDE.md／AGENTS.md は、エージェントのコンテキストにセッションごとに毎回読み込まれます。package.json を言い換えたり、ファイルツリーを貼り付けたり、モデルに「クリーンなコードを書く」よう指示したりする行は、トークンを消費し、本当に重要な2つのルールと競合します。specpack audit はそうした行を見つけます。specpack init を使えば、無駄を省いた状態から始められます。

Node ≥ 18。アカウントは不要です。audit と init がネットワークにアクセスすることはありません。

---

specpack audit — メモリファイルのどれだけが役に立っていませんか？

各行を残す、削除（削除しても何も変わりません。ロールプレイの前置き、一般的なアドバイス、マニフェストの言い換え、重複、強調のしすぎ、散文）、または別ファイルへ移す（内容は正しいものの、状況によって必要になるもの。ファイルツリー、スキーマのダンプ、エンドポイント一覧、長いコードブロック、セットアップ／デプロイのセクションなど。別ファイルに移し、@docs/… で参照します）に分類します。ルールは、ブラウザツールの prompt-generator-website.com/claude-md-audit と同じです。

一般的なファイルでの実際の出力：

$ npx specpack audit CLAUDE.md
CLAUDE.md  59% bloat  · 44 lines · ~341 tokens every session
  10 keep · 12 cut · 15 offload of 37 non-empty lines · ceiling 200, trimmed files land near 60
  Over half of this file is doing nothing. It is not neutral weight — it is what your real rules are competing against.

     3  cut     You are an expert senior full-stack developer with 10 years of experience.
        ↳ role-play preamble: CLAUDE.md is project memory, not a system prompt. "You are an expert…" costs tokens and changes nothing about the code produced.
     4  cut     Please always write clean, readable and maintainable code.
        ↳ default behaviour: Removing this line does not make the model write worse code — it already tries to do this. It only dilutes the lines that matter.
     5  cut     IMPORTANT: follow best practices at all times.
     …
    12  cut     - Next.js 15.1
        ↳ restates a manifest: package.json / composer.json / requirements.txt already state this, and the agent reads them. Keep it only if the version pin has a non-obvious reason.
     …
    18  offload ## Database schema
        ↳ situational section: Only a fraction of your sessions need this. Move the section to its own file and point at it with @docs/… so it loads when the task asks for it.
     …
    31  offload src/
        ↳ file tree: Root of a pasted directory tree. The agent can run ls and get the real one — a copy goes stale after the first refactor.
     …
  Trimmed copy (8 lines): specpack audit CLAUDE.md --trimmed

引数を指定しない場合、カレントディレクトリ内のすべてのエージェントファイルを検査します。対象は CLAUDE.md、AGENTS.md、.cursorrules、.windsurfrules、.github/copilot-instructions.md、CLAUDE.local.md、.cursor/rules/*.mdc です。- を指定すると標準入力を読み込みます。

オプション
--trimmed	残す行だけのバージョンを出力します（> CLAUDE.trimmed.md）
--json	各行の判定、ルール、理由に加え、統計と整理後のファイルを出力します
--all	残す行とその理由も一覧表示します
--max-bloat <pct>	ファイルがしきい値を超えた場合、終了コード 1 を返します

CI での利用

# .github/workflows/agent-files.yml
name: Agent files
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx -y specpack audit --max-bloat 30

specpack init — リポジトリにすでに記載されている内容から、簡潔な AGENTS.md を作成

package.json（スクリプト、ロックファイルから判定したパッケージマネージャー、フレームワーク）、tsconfig.json、Prisma スキーマ、pyproject.toml／requirements*.txt（uv、Poetry）、composer.json、go.mod、Cargo.toml、Gemfile、Makefile、Docker Compose、.nvmrc、.env.example、.claude/commands を読み込みます。ファイルに記載されている内容だけを書き込みます。推測はせず、パッチバージョンや「あなたはエキスパートです」といった前置きも追加しません。検出できる情報がないセクションは省略します。

Next.js + Prisma のリポジトリでの実際の出力：

$ npx specpack init
✓ Wrote AGENTS.md (37 lines, 0% bloat)
  Scanned from package.json, tsconfig.json, prisma/schema.prisma, .nvmrc, docker-compose.yml, .env.example, .gitignore, .claude/commands/.

# AGENTS.md — ledgerly

Invoicing app for freelancers. A web application.

## Stack
- Next.js (App Router)
- Tailwind CSS
- Zod
- Stripe
- Vitest
- Playwright
- ESLint
- TypeScript (strict)
- Prisma + PostgreSQL (schema: prisma/schema.prisma)
- Local services via Docker Compose (docker-compose.yml): db

## Commands
- `pnpm dev` — `next dev --turbopack -p 3001` (port 3001)
- `pnpm build` — `next build`
- `pnpm start` — `next start`
- `pnpm test` — `vitest run`
- `pnpm test:e2e` — `playwright test`
- `pnpm lint` — `next lint`
- `pnpm db:migrate` — `prisma migrate dev`
- `pnpm db:seed` — `tsx prisma/seed.ts`
- `docker compose up -d`

## Project rules
These are things the agent cannot guess from the code. Follow them exactly.
- Use pnpm (pnpm-lock.yaml), not npm or yarn — another package manager ignores the lockfile.
- Runtime: Node 20 (.nvmrc).
- Environment variables are listed in `.env.example`; the real `.env` is git-ignored — do not commit it.

その後、プロジェクトのルールに、自分だけが知っているルールを追加します。ここが重要な部分です。

オプション
--format agents	AGENTS.md（デフォルト）
--format claude	CLAUDE.md — AGENTS.md がある場合は @AGENTS.md を読み込み、Claude Code 固有の情報（スラッシュコマンド、.mcp.json サーバーなど）も含めます
--format cursor	.cursor/rules/project.mdc（常に適用されるルール）
--format all	3つすべて
--dry-run / --force	プレビュー／上書き（既存のファイルは、これらの指定がない限り上書きされません）

specpack spec — 新規プロジェクト向けの完全なビルド仕様書

まだ存在しないプロジェクトの場合、prompt-generator-website.com では、アンケート（SaaS、eコマース、ビジネスサイト、マーケットプレイス、ブログ、Webアプリ、 ランディングページの7種類のプロジェクト）から、技術スタック、データベーススキーマ、認証、種類ごとの 機能、ページ、デザイン、SEO、セキュリティ、法務、デプロイ、ファイル構成を含む完全な仕様書を作成します。さらに、 ビルド全体を通じてエージェントが仕様に沿って作業できるようにするAGENTS.md、 CLAUDE.md、.cursor/rules/project.mdc、.cursorrules、.windsurfrules、 .github/copilot-instructions.mdも生成します。

# AI drafts the answers from a description (10–40 s), then the spec is generated
npx specpack spec --describe "Booking app for dog groomers with deposits and SMS reminders" --out ./groombook

# your own answers (see GET /questions in the API)
npx specpack spec --answers answers.json --type saas

# or answer the questionnaire in the terminal
npx specpack spec

仕様エンジンは決定論的です。同じ回答からは常に同じバイト列が生成されます。アカウント登録なしで無料で利用でき、 仕様書2件とAIドラフト3件を作成できます。さらに利用するには、7日間パスまたはProを prompt-generator-website.com/pricingで購入してください。その後、 specpack login pgw_…（またはSPECPACK_API_KEY）を実行します。specpack whoamiで残りの利用可能数を確認できます。

MCP サーバー

Claude Code、Cursor、Windsurf、VS Code、その他あらゆるMCPクライアントで使える7つのツール：

ツール	実行場所
audit_agent_file	ローカル	膨張スコア、削減または別ファイルへ移す行とその理由、整理後のコピー
draft_agent_file	ローカル	マニフェストから簡潔なAGENTS.md／CLAUDE.md／Cursorルールを作成します（内容を返すだけで、書き込みは行いません）
list_project_types	API	7種類のプロジェクト
get_questionnaire	API	指定した種類のすべての質問。エージェントが会話とリポジトリをもとに回答を入力します
generate_spec	API	仕様書とエージェント用ファイルを生成します。output_dirが指定されている場合はそこに書き込みます（対象はfilesで選択）。サーバー上でAIは使用しません
draft_answers	API	説明をもとにAIがアンケートに回答します（AIドラフトを使用）
get_usage	API	プランと残りの利用可能数

Claude Code

claude mcp add specpack -- npx -y specpack mcp

Cursor（.cursor/mcp.json）、Windsurf、Claude Desktop

{
  "mcpServers": {
    "specpack": { "command": "npx", "args": ["-y", "specpack", "mcp"], "env": { "SPECPACK_API_KEY": "" } }
  }
}

リモート、インストール不要（ストリーミング可能なHTTP。audit_agent_fileとdraft_agent_fileはローカルファイルを読み取るため、ローカルサーバーでのみ利用できます）： https://prompt-generator-website.com/mcp — 任意のヘッダー Authorization: Bearer pgw_…。

claude mcp add --transport http specpack https://prompt-generator-website.com/mcp

ライブラリ

import { audit, scanProject, renderAgentsMd, SpecpackClient } from "specpack";

const { stats, lines, trimmed } = audit(fs.readFileSync("CLAUDE.md", "utf8"));
console.log(`${stats.bloat}% bloat`, lines.filter((l) => l.verdict === "cut").length, "lines to cut");

const agentsMd = renderAgentsMd(scanProject("."));

const client = new SpecpackClient({ apiKey: process.env.SPECPACK_API_KEY });
const draft = await client.draft("A booking app for dog groomers");
const spec = await client.createSpec(draft.type, draft.answers); // spec.spec, spec.files["AGENTS.md"]…

createMcpServer()はspecpack/mcpからエクスポートされます。APIエラーはSpecpackErrorで、code （quota_exceeded、unauthorized、invalid_requestなど）、status、upgradeUrlを持ちます。

リファレンス

• 終了コード：0 正常 · 1 失敗、または--max-bloat超過 · 2 使用方法のエラー、またはクォータ超過。
• 環境変数：SPECPACK_API_KEY、SPECPACK_API_URL（テスト用）、NO_COLOR。
• キーの保存先：~/.config/specpack/config.json（$XDG_CONFIG_HOMEに対応）、モード600。
• HTTP API：API-V1.md。
• プライバシー：auditとinitはローカルファイルを読み取りますが、データを送信しません。specは回答または説明をprompt-generator-website.comに送信します。

ライセンス

MIT © Kipdev