Ship-ready Next.js Starter Checklist

启动一个面向快速交付的 Next.js 项目时，用来检查 Next.js 初始化、质量门禁、Agent Harness、测试机制和交付闭环的清单。

Ship-ready Next.js Starter Checklist

这份清单服务一个很具体的目标：启动一个可以快速 ship 的 Next.js 项目，同时把工程结构和 Agent Harness 一起搭好。

它的默认使用场景是：新建一个 Web / 全栈项目时，先用这页检查项目基座有没有到位。初版重点放在 Next.js 应用、质量门禁、Agent 协作、测试机制和交付闭环。数据库、Auth、支付、队列和后台任务这类 full-stack 模块后续可以继续补进来。

Starter checklist

勾选只保存在当前页面会话里；点击条目切换状态，右侧箭头跳到对应说明。

0/5

使用方式

把顶部 checklist 当成启动前或启动后的验收目录。每完成一项就勾选一次；勾选状态只保存在当前页面会话里，刷新页面后会清空。

初版不要追求把所有命令自动化。更重要的是让新项目有一条清楚的落地路径：先能跑起来，再接质量门禁，再让 Agent 读得懂、测得住、交付得出去。

Next.js 初始化

这一项确认项目的基础形态已经清楚。它决定后面目录、路由、组件、环境变量和部署命令有没有稳定入口。

完成标准：

用官方 Next.js 初始化流程创建项目，优先选择 App Router、TypeScript、Tailwind CSS 和 src/ 目录。
包管理器统一到 pnpm，并在 package.json 写入 packageManager。
清理默认模板内容，保留一个能说明项目方向的最小首页。
明确 src/app、src/components、src/lib、public、docs、.agents/skills 等目录的职责。
常用脚本至少包括 dev、build、start、check、fix、test。

建议命令：

corepack enable
pnpm create next-app@latest
pnpm install
pnpm dev

初始结构可以先保持简单。不要为了看起来完整而提前创建大量空目录；等真实模块出现后，再按功能边界把它们放进对应位置。

质量检查

这一项负责把低价值返工提前拦掉。格式化、lint、import 排序、框架规则和文件复杂度都应该进入本地命令，别靠人眼反复检查。

完成标准：

接入 Ultracite / Biome，统一格式化、lint 和 import 排序。
pnpm run check 能作为只读质量检查命令。
pnpm run fix 能执行安全自动修复。
针对项目约束加入硬规则，例如禁止绕过本地 i18n navigation、限制 TS/TSX 文件和函数过长。
把质量门禁写进 docs/tooling/quality-gates.md 或同类文档，后续修改脚本和规则时同步更新。

参考脚本：

{
  "scripts": {
    "check": "ultracite check",
    "fix": "ultracite fix"
  }
}

质量门禁的重点不在配置数量。它应该优先约束那些会真实拖慢 ship 的问题：格式漂移、错误 import、过大的组件、失控的 client boundary、缺少本地验证入口。

Agent Harness

这一项确认新开的 Agent session 能读懂项目、选择正确工具、执行任务、验证结果，并把新的稳定知识写回仓库。

完成标准：

根目录有 AGENTS.md，写清楚仓库工作方式、关键规则和 docs system 入口。
有项目长期知识入口，例如 docs/index.md、docs/DOCS.md、docs/<domain>/DOCS.md。
有 CONTEXT.md 或等价的领域词表，定义产品、模块和交付语言。
.agents/skills 和 skills-lock.json 能记录当前项目实际使用的 skills。
skills 至少覆盖拷问方案、项目文档、TDD、模块设计和架构改进。
MCP / 浏览器工具的使用规则有明确入口，UI 变更需要真实浏览器验证。

建议优先安装的 skills：

npx skills add https://github.com/mattpocock/skills --skill grilling
npx skills add https://github.com/mattpocock/skills --skill tdd
npx skills add https://github.com/mattpocock/skills --skill codebase-design
npx skills add https://github.com/mattpocock/skills --skill improve-codebase-architecture
npx skills add https://github.com/multicul-silver-wolf/agent-docs-system-skill --skill project-docs-system

Agent Harness 的关键是让上下文、skills、tools 和验证路径组合起来。单独装一个 skill 没有多大意义；它需要和仓库文档、质量命令、测试命令、浏览器验证和 Git 交付一起工作。

Test 机制

这一项确认项目有最小但有效的测试入口。初始项目不需要把测试覆盖率做满，但必须有能保护核心行为的 tracer bullet。

完成标准：

接入 Vitest，并提供 pnpm test。
为纯逻辑、路由辅助、i18n 配置、内容 loader、核心组件契约补最小测试。
测试文件靠近被测代码，或者放在清楚的 __tests__ 边界里。
UI 变更除了单测，还要打开浏览器检查关键路由。
需要性能或 SEO 的页面，保留 Lighthouse / PageSpeed / 浏览器控制台检查证据。

参考脚本：

{
  "scripts": {
    "test": "vitest run"
  }
}

测试的重点是守住能影响 ship 的核心行为。比如多语言路由、导航生成、内容解析、按钮 primitive、section copy contract，这些比给每个样式细节写断言更有价值。

Git / Vercel / CI

这一项确认项目能从本地改动进入线上，并且每次交付都有可追踪的验证结果。

完成标准：

初始化 Git，明确默认分支和提交信息风格。
.gitignore 排除本地缓存、构建产物、密钥和临时文件。
GitHub 仓库创建完成，远端指向清楚。
GitHub Actions 至少运行 pnpm install、pnpm run check、pnpm test、pnpm run build。
Vercel 项目已经连接仓库，环境变量以 Vercel 为事实来源。
上线后检查关键路由、浏览器控制台、基础性能和 SEO。

参考 CI 形状：

name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm run check
      - run: pnpm test
      - run: pnpm run build

Vercel 相关环境变量不要散落在多个本地文件里。能通过 Vercel 管理的，就让 Vercel 成为事实来源；本地只保留开发必要的占位和说明。

维护方式

这页和 Agent Skills 收集一样，应该长期更新。它不需要一次写成最终版。

维护规则：

新项目里出现了稳定、可复用的初始化动作，就补进对应分组。
某个工具被替换，例如 Biome、测试框架、部署平台或 MCP 入口变化，就同步更新完成标准和命令。
如果 full-stack 能力开始稳定，例如数据库、Auth、支付、队列、后台任务，就新增分组，不要硬塞进当前五项。
每次扩展 checklist，都要保留顶部 checklist 和正文解释的一一对应关系。
如果某项已经变成自动化脚本，正文要写清楚脚本做了什么，以及人还需要检查什么。

Ship-ready Next.js Starter Checklist