Shipr

面向 AI 时代的软件项目脚手架。

传统脚手架解决的是“创建项目”：选择 React、Vue、Next.js，生成代码目录，安装依赖，初始化工程。

Shipr 想解决的是“创建团队能力”：把一个普通代码仓库升级成 Agent-ready repository，让项目拥有可被 AI Agent 消费的需求、上下文、流程、质量门禁和交付资产。

它不是另一个前端模板，也不是替代 Cursor、Claude Code、Codex、Dify 或 LangFlow 的平台。它更像一个项目级 AI 能力层生成器：为项目安装 .ai/ 能力层，让 PM、设计、开发、测试、部署之间的产物可以被追踪、复用、校验和继续执行。

一句话定位

Shipr 是面向 AI Agent 的项目能力层脚手架。

它的完整产品设计覆盖 AI 软件交付全链路，但 MVP 只聚焦最小闭环：让项目具备可被 AI Agent 消费的需求、上下文、任务和质量门禁。

核心原则

1. 从创建项目到创建团队能力

第一步不再是选框架，而是选能力。

npx shipr-ai my-project

交互式选择：

请选择需要安装的能力：

[x] Spec Contract
[x] UI Contract
[x] API Contract
[x] Implementation Plan
[x] Coding Agent Context
[x] Review Gate
[ ] Test Contract
[ ] Deployment Contract

生成：

my-project/
├── .ai/
│   ├── agents/
│   ├── workflows/
│   ├── contracts/
│   ├── context/
│   ├── gates/
│   └── mcp/
├── docs/
├── src/
└── deploy/

2. 不生成死产物

Shipr 不追求生成更多文件，而是只生成会被下游消费、校验或执行的产物。

例如，单独的 prototype.html 对开发通常不可复用，容易变成一次性展示物。更有价值的产物是：

• screen-map.md：页面清单
• interaction-spec.md：交互说明
• state-matrix.md：加载、空、错误、成功状态
• component-map.md：页面到组件的映射
• api.yaml：前后端共享的 API 契约
• acceptance-criteria.md：开发和测试共同使用的验收标准

可视化 Demo 可以存在，但它应该是结构化产物的预览层，而不是下游开发依赖的源头。

3. 产物契约优先

核心不是“AI 帮每个角色生成文件”，而是“生成角色之间可交接的产物契约”。

Product Contract
  -> Design Contract
  -> API Contract
  -> Implementation Contract
  -> Test Contract
  -> Deployment Contract

每个产物都必须回答：

• 谁生成
• 生成什么
• 给谁使用
• 下游如何消费
• 如何判断产物合格

4. Workflow 比 Skill 更重要

单个 Skill 或 Prompt 只能解决局部问题。真正有价值的是把项目内的 AI 能力编排成可执行工作流。

workflow: delivery
steps:
  - id: requirement
    output: docs/prd.md
    gate:
      - goals_required
      - non_goals_required
      - acceptance_criteria_required

  - id: design_contract
    output:
      - docs/screen-map.md
      - docs/component-map.md
      - docs/state-matrix.md
    gate:
      - every_screen_has_state
      - every_action_has_feedback

  - id: implementation_plan
    output: docs/implementation-plan.md
    gate:
      - tasks_are_traceable_to_requirements
      - risky_changes_are_marked

  - id: coding
    gate:
      - tests_must_pass
      - review_required

执行：

shipr run delivery

调用链路：

Spec Agent
  -> Design Contract Agent
  -> Architect Agent
  -> Coder Agent
  -> Reviewer Agent

5. 完整产品设计，MVP 切片执行

长期愿景可以覆盖完整交付链路：

需求分析 -> PRD -> 设计契约 -> 技术方案 -> 任务拆解 -> 开发 -> Review -> 测试 -> 部署 -> 文档沉淀

但第一版不做大而全平台。MVP 只验证一个关键问题：

一个普通项目经过 Shipr 初始化后，AI Coding Agent 的交付质量是否明显提升。

为什么需要它

当前 AI Coding 工具大多只覆盖软件交付链路的一部分：

| 产品 | 擅长 | | --- | --- | | Claude Code | Coding | | Codex | Coding | | Cursor | IDE | | Spec Kit | 需求驱动 | | GStack | 项目模板 | | Multica | Agent 管理 | | LangFlow | 工作流 | | Dify | Agent 平台 |

市场上缺少一个项目级标准层，把需求、上下文、角色、流程、质量门禁和工具连接安装进仓库。

Shipr 的目标不是替代这些工具，而是为它们提供更好的项目输入。

与现有工具的关系

Shipr 不应该和 agent harness、coding agent、skill 包或 spec-first 工具在同一层竞争。

更准确的分层是：

| 类型 | 代表 | 主要解决 | | --- | --- | --- | | Coding Agent / IDE | Claude Code、Codex、Cursor | AI 如何读代码、改代码、运行命令、提交实现 | | Agent Harness | Trellis、GSD | Agent 如何记忆、接力、编排任务、维护任务状态 | | Skill / Methodology | Everything Claude Code、Superpowers、Skills | Agent 遇到某类任务时应该如何执行 | | Spec-first 工具 | Spec Kit | 需求规格如何驱动开发 | | 项目模板 | gstack | 项目如何初始化、选择技术栈 | | Shipr | 本项目 | 项目如何被初始化成可由 AI 团队交付的形态 |

因此，Shipr 的差异不是“我也有记忆、hook、sub-agent、任务状态机”，而是：

在任务进入 coding agent 或 agent harness 之前，先把项目的需求、设计、API、实现计划和质量门禁整理成可消费的产物契约。

它更像这些工具的上游输入层：

Shipr
  -> 生成项目级 Contract / Context / Gate
  -> 交给 Codex / Claude Code / Cursor / Trellis / GSD 执行
  -> 执行结果再回写到项目资产

和 Spec Kit 的区别

Spec Kit 关注的是：

spec -> plan -> task -> implement

Shipr 关注的是更宽的交付契约链：

requirement
  -> product contract
  -> design contract
  -> api contract
  -> implementation contract
  -> review / test / deploy gate

它不是只让规格驱动代码，而是让 PM、设计、开发、测试、部署之间的交接产物都变成可追踪、可复用、可校验的项目资产。

和 Trellis / GSD 的区别

Trellis / GSD 更偏向 agent harness：任务生命周期、会话连续性、上下文注入、hook、sub-agent 协作。

Shipr 不应该重复实现这些能力。它应该负责在任务进入 harness 之前，生成更好的上游输入：

需求是否清楚
页面状态是否完整
API 契约是否可实现
任务是否能追溯到需求
Review Gate 是否能阻止低质量输出

和 Skills / Superpowers 的区别

Skills / Superpowers 更像能力方法库，告诉 Agent “遇到某类任务时怎么做”。

Shipr 更像项目能力安装器，负责把这些能力安装进具体项目，并定义它们如何协作、输出什么、由谁消费、如何验收。

典型用户

Shipr 尤其适合：

• 独立开发者
• 技术型创始人
• 1-3 人小团队
• 企业内部创新项目负责人
• 会写代码但缺少产品、设计、测试、部署支持的工程师

它的目标不是让一个人“完全替代团队”，而是让一个人可以调度一支 AI 交付团队。

用户如何使用

做好以后，用户不会把 Shipr 当成“又一个传统脚手架”，而会把它当成给项目安装 AI 交付团队的入口。

独立开发者：从想法到可运行 MVP

npx shipr-ai my-saas
cd my-saas
shipr spec "做一个给小团队用的客户跟进系统"
shipr plan
shipr run delivery
shipr review

链路：

一句话想法
  -> 结构化 PRD
  -> 页面 / 组件 / API 契约
  -> 实现计划
  -> AI Coding Agent 开发
  -> Review Gate 检查
  -> 可运行版本

技术型创始人：把模糊需求变成开发输入

输入：

我要做一个团队任务看板，支持成员分配、截止日期、状态流转和提醒。

输出：

docs/prd.md
docs/user-story.md
docs/acceptance-criteria.md
docs/screen-map.md
docs/component-map.md
docs/api.yaml
docs/implementation-plan.md
.ai/contracts/product.yaml
.ai/gates/review-checklist.md

此时再交给 Codex、Claude Code、Cursor 或其他 coding agent，输入就不再是一句模糊需求，而是一套结构化上下文和可执行任务。

小团队：统一 AI 协作标准

npx shipr-ai init
shipr add product
shipr add dev
shipr add qa

团队可以约定：

• 任何功能开发前，必须有 docs/prd.md
• 任何进入开发的需求，必须有 docs/acceptance-criteria.md
• 任何 UI 需求，必须有 docs/component-map.md 和 docs/state-matrix.md
• 任何提交前，必须通过 .ai/gates/review-checklist.md

这时 Shipr 不是个人 Prompt 收藏夹，而是团队的 AI 交付流程标准。

完整产品形态

完整版本可以按能力包扩展，但能力包的边界应该围绕“下游可消费产物”，而不是围绕“生成更多文档”。

Product Kit

安装：

shipr add product

生成能力：

• 需求澄清
• PRD Contract
• 用户故事
• 验收标准
• 非目标和边界条件

典型输出：

• docs/prd.md
• docs/user-story.md
• docs/acceptance-criteria.md
• .ai/contracts/product.yaml

下游消费者：

• Design Contract Agent
• Implementation Plan Agent
• Test Contract Agent

Design Kit

安装：

shipr add design

生成能力：

• 页面结构
• 用户路径
• 交互说明
• 状态矩阵
• 组件映射

典型输出：

• docs/screen-map.md
• docs/user-flow.md
• docs/interaction-spec.md
• docs/state-matrix.md
• docs/component-map.md
• docs/ui-spec.md

下游消费者：

• Frontend Agent
• Review Agent
• Test Agent

Dev Kit

安装：

shipr add dev

生成能力：

• 技术方案
• API 契约
• 数据模型
• 任务拆解
• Coding Agent 上下文

典型输出：

• docs/architecture.md
• docs/implementation-plan.md
• docs/api.yaml
• docs/data-model.md
• .ai/context/project.md
• .ai/context/standards.md

下游消费者：

• Coding Agent
• Review Agent
• QA Agent

QA Kit

安装：

shipr add qa

生成能力：

• 测试契约
• 测试用例
• 回归检查
• 验收门禁

典型输出：

• docs/test-plan.md
• docs/testcase.md
• tests/playwright.spec.ts
• .ai/gates/test-checklist.md

下游消费者：

• QA Agent
• CI/CD
• Release Gate

Ops Kit

安装：

shipr add ops

生成能力：

• 运行时要求
• 环境变量说明
• 部署计划
• CI/CD 配置
• 容器化和 K8S 配置

典型输出：

• deploy/deploy-plan.md
• deploy/runtime-requirements.md
• deploy/.env.example
• deploy/Dockerfile
• deploy/helm/

下游消费者：

• Deploy Agent
• CI/CD
• 运维人员

MVP 设想

第一版只做 Agent-ready Repository，不做完整平台。

MVP 能力：

• Spec Contract
• UI / API Contract
• Implementation Plan
• Quality Gates
• Agent Context

创建项目：

npx shipr-ai my-project

或接入已有项目：

npx shipr-ai init

生成结构：

project/
├── .ai/
│   ├── agents/
│   │   ├── product.md
│   │   ├── architect.md
│   │   ├── coder.md
│   │   └── reviewer.md
│   ├── workflows/
│   │   └── delivery.yaml
│   ├── contracts/
│   │   ├── product.yaml
│   │   ├── ui.yaml
│   │   └── api.yaml
│   ├── context/
│   │   ├── project.md
│   │   ├── constraints.md
│   │   ├── standards.md
│   │   └── decisions.md
│   └── gates/
│       ├── prd-checklist.md
│       ├── implementation-checklist.md
│       └── review-checklist.md
├── docs/
│   ├── prd.md
│   ├── screen-map.md
│   ├── component-map.md
│   ├── implementation-plan.md
│   └── acceptance-criteria.md
└── src/

核心命令：

shipr spec
shipr plan
shipr run delivery
shipr review

MVP 不优先做：

• 高保真设计稿
• 独立工作流平台
• 完整部署平台
• 大而全 Agent 市场
• 无条件生成 Dockerfile、Jenkinsfile、Helm

项目目标

Shipr 期望成为 AI 原生软件交付的项目初始化工具：

• 不只初始化代码，也初始化团队协作能力
• 不只生成 Prompt，也生成可执行 Workflow
• 不只生成文档，也生成下游可消费的产物契约
• 不只服务 Coding，也连接产品、设计、研发、测试、部署
• 不绑定单一模型、IDE 或框架
• 让每个项目都可以拥有自己的 .ai/ 能力层

Roadmap

• [ ] 定义 .ai/ 标准目录结构
• [ ] 定义 Contract / Context / Gate 三类核心资产
• [ ] 实现 shipr init 项目初始化命令
• [ ] 实现 Spec Contract 生成
• [ ] 实现 Implementation Plan 生成
• [ ] 实现 Quality Gate 检查清单
• [ ] 支持 shipr run delivery 执行最小工作流
• [ ] 支持 MCP 配置生成
• [ ] 支持已有项目接入 .ai/ 能力层
• [ ] 扩展 Product / Design / Dev / QA / Ops Kit

状态

项目处于概念设计与 MVP 探索阶段。

当前重点不是做一个新的 React/Vue 脚手架，而是验证一个更大的方向：AI 时代的脚手架应该从“创建项目”升级为“创建团队能力”，并把这种能力沉淀为项目内可执行、可校验、可复用的 .ai/ 能力层。