specpack

specpack

检查并生成 AI 编码 Agent 会读取的文件——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 会在每次会话中加载到 Agent 的上下文中。每一行重复说明 package.json 内容、粘贴文件树，或告诉模型“编写整洁的代码”，都会消耗 token，并与真正重要的两条规则争夺注意力。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

不带参数时，它会检查当前目录中的所有 Agent 文件：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 时会导入该文件，并包含 Claude Code 专属内容（斜杠命令、.mcp.json 服务）
--format cursor	.cursor/rules/project.mdc（始终应用的规则）
--format all	三种格式
--dry-run / --force	预览 / 覆盖（否则绝不覆盖已有文件）

specpack spec — 新项目的完整构建规范

对于尚不存在的项目，prompt-generator-website.com 会将一份问卷（7 种项目类型：SaaS、电商、企业网站、市场平台、博客、Web 应用、 落地页）转换为完整的规范，涵盖技术栈、数据库架构、身份验证、特定类型的功能、页面、设计、SEO、安全、法律、部署、文件结构，以及 AGENTS.md、 CLAUDE.md、.cursor/rules/project.mdc、.cursorrules、.windsurfrules 和 .github/copilot-instructions.md，确保 Agent 在整个构建过程中遵循规范。

# 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 份规范和 3 份 AI 草稿。如需更多：可购买 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	某类型的全部问题；Agent 会根据对话和代码仓库填写答案
generate_spec	API	规范和 Agent 文件；若提供 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