Documenso AI 开发命令 continue.md 深度解析：跨会话规格续接与自主工程闭环

Documenso AI 开发命令 continue.md 深度解析：跨会话规格续接与自主工程闭环

【免费下载链接】documensoThe Open Source DocuSign Alternative.项目地址: https://gitcode.com/GitHub_Trending/do/documenso

continue.md是 Documenso 仓库中 OpenCode 自定义命令（slash command）之一，专门用于“接续上一次会话未完成的功能规格实现”。它把“读规格 → 评估现状 → 补齐差异 → 类型检查/静态检查/E2E 测试”固化成一套可重复执行的自主工作流。读完本文，你能完整理解该命令的指令契约、每一步检查命令在仓库中的真实落点（Biome、tsc、Playwright 等），以及它与implement.md、.agents/plans/规格目录共同构成的 AI 协作开发链路。

命令定位：为什么需要“continue”而不是重新“implement”

Documenso 为 AI 编码代理准备了一套 OpenCode 命令，位于 .opencode/commands/ 目录，包括 implement.md、commit.md、create-plan.md、create-scratch.md、create-justification.md、create-documentation.md、interview.md 等，而 continue.md 是其中“续接型”命令。

对照 implement.md 可以看出两者的分工：implement 面向全新规格，流程是“读规格 → 用 TodoWrite 拆任务 → 直接实现”；而 continue 额外强制了两个前置动作——评估当前状态（Assess current state）和对照规格确定剩余工作（Determine what remains）。这解决的正是长会话被中断后的典型问题：AI 不知道上一次会话写到了哪里、哪些代码已经存在、哪些还是半成品。

Frontmatter 指令契约：description 与 argument-hint

continue.md 文件头部的 YAML frontmatter 定义了命令的元信息：

--- description: Continue implementing a spec from a previous session argument-hint: <spec-file-path> ---

• description用于在命令列表中展示该命令的用途：从上一次会话续接一份规格（spec）的实现。
• argument-hint: <spec-file-path>表明调用时需要传一个参数：规格文件的路径。正文中的$ARGUMENTS占位符会被该实参替换，例如“Read the spec at$ARGUMENTS”即“读取 <你传入的路径> 处的规格文件”。

从源码结构看，规格文件通常来自仓库的 .agents/plans/ 目录——其中存放着十余份以“三词 ID + 功能名”命名的规格文档（如 bright-emerald-flower-bullmq-background-jobs.md、smooth-coral-earth-database-rate-limiting.md），均带date与title的 frontmatter，并包含 Context、Current Architecture 等章节。这种“计划文件带 frontmatter、正文描述背景与目标架构”的格式，正是 continue 命令能够“读取并对照规格”的前提。

六步任务流水线：从读规格到续接实现

文档的核心是 “Your Task” 一节给出的六步流程：

1. 读取规格：读$ARGUMENTS指向的 spec 文件；
2. 读取 CODE_STYLE.md：加载代码格式与模式约定；
3. 评估当前状态：检查 git 未提交改动、跑测试确认通过/失败情况（若存在 E2E 测试）、审阅已有实现；
4. 确定剩余工作：把规格与当前实现逐项对比，找出差距；
5. 用 TodoWrite 规划剩余任务，形成可勾选的任务清单；
6. 持续实现直至完成。

其中第 3、4 步是 continue 区别于 implement 的灵魂。第 4 步隐含了一个“规格即验收标准”的思想：spec 中列出的需求就是完成判据，实现进度必须逐项回填。

评估现状：四条命令及其在仓库中的真实落点

文档给出的现状检查命令如下：

git status # See uncommitted changes git log --oneline -10 # See recent commits npm run typecheck -w @documenso/remix # Check for type errors npm run lint:fix # Check for linting issues

结合仓库实际脚本定义，可以逐条核实这些命令的落点：

• git status/git log --oneline -10：识别上一次会话遗留的未提交改动与最近提交，判断“代码写了一半”还是“已提交推进”。
• npm run typecheck -w @documenso/remix：-w表示在 npm workspace（根 package.json 声明了"workspaces": ["apps/*", "packages/*"]）中定位@documenso/remix包执行其脚本。查 apps/remix/package.json 可知该包的typecheck定义为react-router typegen && tsc——先做 React Router 的类型生成，再跑完整 TypeScript 编译检查。这也是为什么续接时必须先跑它：Remix/React Router 的路由类型（Route.Params、Route.LoaderData）依赖 typegen 产物。
• npm run lint:fix：根 package.json 中定义为biome check --write .，即由 Biome 对整个仓库做检查并自动修复。修复后再复查，可快速抹平格式类差异。

文档还要求在跑完命令后通读已有代码，回答三个问题：已实现什么（What's already implemented）、半成品是什么（What's partially done）、尚未开始的是什么（What's not started yet）。这一步的输出直接决定后续 TodoWrite 里应列哪些任务。

实现规范：CODE_STYLE.md 与代码质量红线

编码期间的规则

文档 “During Implementation” 小节规定：

• 严格遵循 CODE_STYLE.md（2 空格缩进、双引号、大括号必写等）；
• 遵循 workspace 层对 TypeScript、React、TRPC 模式和 Remix 约定的规则；
• 每完成一个任务就勾选 todo；
• 按逻辑块（logical chunks）提交，而不是把所有改动堆成一个大提交。

CODE_STYLE.md 正文覆盖 TypeScript 约定、导入与依赖、函数、React 组件、错误处理、async/await、空白格式、命名、模式匹配、数据库与 Prisma、TRPC 模式等 12 个章节，例如“优先type而非interface”“优先早返回/守卫子句”等；AGENTS.md 则补充了 TRPC 路由文件的组织方式（每路由一个文件routers/teams/create-team.ts、配套.types.ts、Z[RouteName]RequestSchema命名）与 i18n 宏用法。两条规则链互为补充：CODE_STYLE.md 管“怎么写”，AGENTS.md 管“工程命令与目录约定”。

代码质量红线

“Code Quality” 小节列出六条硬性要求，其中大部分能在仓库中找到对应实现：

• 禁止桩实现（No stubbed implementations）；
• 处理边界条件与错误场景，错误信息必须带上下文；
• 所有 I/O 一律使用 async/await；
• 抛错必须使用 AppError 类——对应仓库中的 packages/lib/errors/app-error.ts，其中定义了AppErrorCode枚举（NOT_FOUND、UNAUTHORIZED、FORBIDDEN、LIMIT_EXCEEDED、RECIPIENT_OUT_OF_TURN等数十种业务错误码），AGENTS.md 还进一步要求前端捕获时用AppError.parse(error)解析错误码；
• 表单校验用 Zod、表单状态用 react-hook-form——这与代码库中 tRPC 路由普遍使用Zod定义输入 Schema 的做法一致。

测试策略：只为“非平凡功能”写 E2E

文档特别强调“E2E 测试耗时，只对非平凡功能写测试”，并给出具体规则：

• E2E 测试写在packages/app-tests/e2e/，使用 Playwright；
• 只测关键用户流和边界场景；
• 遵循代码库既有 E2E 测试模式；
• 测试名要能自解释；
• 琐碎改动（简单 UI 微调、小重构）直接跳过。

仓库结构印证了这一策略：packages/app-tests/e2e/ 下按功能域划分了约三十个测试目录（envelope-editor-v2/、document-auth/、teams/、webhooks/等），API 类测试集中在e2e/api/。packages/app-tests/playwright.config.ts 的配置也解释了“为什么 E2E 昂贵”：testDir: './e2e'、fullyParallel: true、workers: 10（注释说明 10 个 worker 主要服务 API 测试）、CI 下maxFailures: 1且retries: 4（本地retries: 1）、失败时保留 trace 与 video（trace: 'retain-on-failure'、video: 'retain-on-failure'）、actionTimeout: 15s/navigationTimeout: 30s，并通过 cookie 关闭动画以保证测试稳定。

自主工作流：六步循环直至收敛

文档的 “Autonomous Workflow” 是 continue 命令的执行引擎，要求代理在以下循环中连续工作、不主动中断：

1. Implement：实现当前 todo 项的代码；
2. Typecheck：npm run typecheck -w @documenso/remix校验类型；
3. Lint：npm run lint:fix修复静态检查问题；
4. Test：非平凡改动则运行npm run test:dev -w @documenso/app-tests；
5. Fix：测试失败则修复并重跑；
6. Repeat：推进到下一个 todo，直到清单清空。

对照 packages/app-tests/package.json 的脚本定义可验证该循环的测试环节：test:dev即NODE_OPTIONS='--import tsx' playwright test（用 tsx 直接跑 TypeScript 用例，无需预编译）；test-ui:dev在其后追加--ui打开 Playwright 的交互式 UI；test:e2e则通过start-server-and-test先启动@documenso/remix生产服务并等待http://localhost:3000就绪后再跑playwright test $E2E_TEST_PATH，支持用环境变量只跑指定路径的用例。

停止条件：何时报喜、何时求助

文档明确划定了两类停止信号，避免代理无限循环或擅自扩大范围：

完成并报告成功（Stop and report success）当且仅当：

• 规格的全部需求已实现；
• Typecheck 通过；
• Lint 通过；
• 已编写（针对非平凡功能）的 E2E 测试通过。

停下来求助（Stop and ask for help）当出现：

• 规格存在歧义，需要澄清；
• 遇到自己无法解决的阻塞问题；
• 需要做明显偏离规格的重大决策；
• 缺少外部依赖。

这套“成功判据可验证（typecheck/lint/test 三绿）、求助条件显式化”的设计，使命令在无人值守场景下既不会提前收工，也不会悄悄改需求。

命令速查表（Commands 小节完整继承）

文档末端的 Commands 一节提供了完整速查，原样整理如下：

# Type checking npm run typecheck -w @documenso/remix # Linting npm run lint:fix # E2E Tests (only for non-trivial work) npm run test:dev -w @documenso/app-tests # Run E2E tests in dev mode npm run test-ui:dev -w @documenso/app-tests # Run E2E tests with UI # Development npm run dev # Start dev server

补充仓库侧的事实注记：

• typecheck由 apps/remix/package.json 定义（react-router typegen && tsc），通过-w @documenso/remix定向执行；
• lint:fix由根 package.json 定义（biome check --write .）；
• test:dev/test-ui:dev定义在 packages/app-tests/package.json；文档速查表中列出的npm run test:e2e（全量 E2E 套件）对应的实现同样位于 app-tests 工作区，[AGENTS.md](https://link.gitcode.com/i/a2b33dd5045ad72ce1d50307403aacd2)的 Build/Test/Lint Commands 一节也将其列为标准命令之一；
• npm run dev在根 package.json 中定义为npm run translate:compile && turbo run dev --filter=@documenso/remix，即先编译 Lingui 翻译产物再用 Turborepo 启动 Remix 开发服务器。

在仓库 Agent 工具链中的位置

把 continue.md 放回整个工具链中看，一条完整的规格驱动开发链路由此拼合：

1. create-plan.md：在 .agents/plans/ 创建新规格（三词 ID + frontmatter）；
2. implement.md：对全新规格从零实现，走“TodoWrite 拆解 → 实现 → 类型/静态检查 → E2E”流程；
3. continue.md：会话中断后，先评估 git 状态与测试现状，再对照规格补齐剩余工作——本文主题；
4. commit.md：实现完成后，按 Conventional Commits（feat/fix/refactor等类型，祈使句主题行，禁止--amend与--no-verify，禁止提交疑似密钥文件）生成规范提交。

也就是说，continue.md 承担的是“长任务断点续跑”这一环：它以 git 与测试状态为事实源，以规格文件为验收标准，以 CODE_STYLE.md/AGENTS.md 为风格与工程约束，最终把 AI 代理约束在“实现—验证—修复”的收敛循环内，直到 typecheck、lint、E2E 全部通过才允许宣告完成。

小结

• continue.md 是 OpenCode 命令，参数为规格文件路径（$ARGUMENTS），核心差异是强制“现状评估 + 剩余工作判定”两步；
• 评估手段是git status、git log --oneline -10、npm run typecheck -w @documenso/remix（=react-router typegen && tsc）、npm run lint:fix（= Biome 自动修复）；
• 实现约束锚定 CODE_STYLE.md 与 AGENTS.md：AppError 抛错、Zod 校验、async/await、按逻辑块提交；
• 测试策略是“非平凡才测”：Playwright 用例集中在 packages/app-tests/e2e/，配置见 packages/app-tests/playwright.config.ts；
• 收敛条件是三重绿灯（typecheck / lint / E2E），歧义、阻塞、偏离规格、缺依赖则停止并求助。

【免费下载链接】documensoThe Open Source DocuSign Alternative.项目地址: https://gitcode.com/GitHub_Trending/do/documenso