# How to Ship your First Product using AI in 2026 (Builder's Guide)
**作者**: Avid
**日期**: 2026-05-15T17:20:34.000Z
**来源**: [https://x.com/Av1dlive/status/2058951175236727025](https://x.com/Av1dlive/status/2058951175236727025)
---
AI is making millionaires every week.
I am shipping products using AI this year
This is what i learned and how you can get started
## Here is why it matters
I am in the process of shipping a SaaS platform.
I've already shipped an MCP server and a GitHub repo which got 2,000 stars.
I'm in the process of also shipping an iOS mobile app.
In the end I've also given you workflow files. If you are building an MCP server, a SaaS web app, or an iOS mobile app or any mobile app, these are the skill files and workflows that you can use to make all of this in one single flow.
> **Avid@Av1dlive**: [原文链接](https://x.com/Av1dlive/status/2055337557140046242)
>
> Stop Swiping on Tinder Today
> I built Tinder for startup founders and it took me less than an hour
> Swipe on founders in your niches. Match. Get icebreakers. DM without cringe
> Apps like SuperappAI make building ios apps super easy
>
> 
# Introduction
Most people are using AI coding tools like smarter autocomplete.
That works for tiny tasks.
It breaks the moment the work becomes multi-step, stateful, or spread across frontend, backend, tests, docs, and release notes.
The real shift is not just using a better model.
The shift is wrapping the model in a repeatable system of instructions, tools, files, and verification so it can work like a reliable software operator instead of a chaotic chat session.
That system is the harness.
This article is a practical playbook for builders.
It shows how to set up a lightweight agent harness inside any repo, how to structure AGENTS.md, how to define reusable skill files, and how that setup should change depending on whether you are building a SaaS web app, a CLI tool, an MCP server, or a mobile app.
The goal is simple.
Turn vague “use agents” advice into a workflow that actually helps people ship products.
## Why most people use agents badly
The common failure mode is obvious.
A builder opens an AI coding tool, pastes a feature request, watches it edit twelve files, and then spends an hour cleaning up the mess.
The problem is usually not just the model.
The problem is that the agent was given no structure, no memory outside the prompt, no stopping conditions, and no real way to verify whether the result was actually correct.
That means the right question is no longer, “What prompt should I use?”
The right question is, “What environment should I build so the agent can work safely, incrementally, and verifiably?”
## What a harness actually is
A useful harness has five parts.
- A working directory the agent can read and modify.
- A durable set of instructions that lives in files, not only in chat history.
- A small library of reusable skills for recurring workflows.
- A verification layer made of tests, QA steps, and output artifacts.
- A stop-and-review loop so the human stays in control.
For builders, that is enough.
You do not need enterprise infrastructure.
You do not need custom orchestration servers.
You do not need a research lab budget.
You need a clean repo structure and clear operating rules.
Here is the minimum layout.
```
project/
.agent/ # Everything the agent uses to operate
AGENTS.md # Global rules, roles, guardrails, and stopping conditions
SKILLS/ # Reusable playbooks for recurring workflows
spec-to-plan/
SKILL.md # Turns a task or spec into an ordered implementation plan
implementation/
SKILL.md # Tells the agent how to execute approved work in small chunks
verification/
SKILL.md # Defines how to test, inspect, and validate the result
release/
SKILL.md # Prepares release notes, migration notes, and handoff docs
docs/ # Working memory shared between you and the agent
TASK.md # The original task, spec, or feature request
PLAN.md # The step-by-step plan generated before coding starts
QA.md # Verification notes, bugs found, screenshots, and test results
RELEASE.md # Final release summary, rollout notes, and upgrade guidance
tests/ # Your safety net; unit, integration, or fixture tests live here
CHANGELOG.md # Running log of meaningful changes across iterations
README.md # Human-facing setup, usage, and project context
```
This structure externalizes memory and procedure.
Instead of trying to keep everything in one giant prompt, the agent reads the right file at the right time and writes its outputs back into the repo.
That is the core idea.
## The core loop
Every product type in this article uses the same loop.
1. Write the task in docs/TASK.md.
2. Ask the agent to convert it into a plan in docs/PLAN.md.
3. Review and approve the plan.
4. Let the agent implement a small chunk.
5. Run verification.
6. Write a QA report.
7. Prepare release notes or next steps.
A good TASK.md is simple and concrete.
```
TASK
Add email and password login to the product.
Requirements:
- Keep existing OAuth login working.
- Add frontend form validation.
- Add backend auth endpoint.
- Add tests for successful and failed login.
- Do not change the billing flow.
```
The Planner converts that into a file-based plan.
The human edits the plan if needed.
Only after approval does the Implementer start writing code.
## The one file every repo should have
Every repo should have one base contract that defines how the agent works.
This file is the difference between random edits and predictable operations.
Paste this into .agent/AGENTS.md.
```
# AGENTS.md
## Mission
Turn product specs into working software through a repeatable loop:
spec -> plan -> implementation -> verification -> release prep.
## Global rules
- Never start coding before writing a plan to `docs/PLAN.md`.
- Never implement more than 3 plan steps before stopping for review.
- Always update `CHANGELOG.md` after meaningful work.
- Prefer existing patterns in the codebase over inventing new abstractions.
- If a task touches auth, payments, database migrations, production infra, or destructive actions, stop and ask for approval before proceeding.
- If uncertain, reduce scope rather than guessing.
- Keep outputs concise, structured, and file-based.
## Standard loop
1. Read `docs/TASK.md`
2. Write `docs/PLAN.md`
3. Wait for approval
4. Implement in small chunks
5. Run relevant verification
6. Write `docs/QA.md`
7. Summarize next actions
## Required artifacts
- `docs/PLAN.md`
- `docs/QA.md`
- `CHANGELOG.md`
## Roles
### Planner
Turns specs into implementation plans with risks, files touched, and acceptance criteria.
### Implementer
Executes approved plan steps, writes code, adds tests, and updates changelog.
### Verifier
Runs checks, reviews outputs, and writes QA notes.
### Release Assistant
Prepares release notes, setup docs, migration notes, and operational handoff.
## Stopping conditions
Stop and escalate when:
- tests fail repeatedly
- the same action loops twice
- required context is missing
- the task requires secrets or production credentials
```
This file gives the agent a durable operating contract.
It also gives the builder something more important.
A way to reason about the agent’s behaviour when things go wrong.
## One harness, four product types
The harness skeleton stays the same across products.
What changes is the meaning of implementation and verification.
This is the key idea.
The harness is not one magic prompt.
It is a repeatable operating model that adapts to the product surface.
## Skill files are the real workflow
A skill file is a small procedural document that tells the agent how to perform a recurring kind of work.
For builders, skill files do three things.
- They reduce repeated prompting.
- They standardize output structure.
- They let the same repo support multiple product workflows cleanly.
The rest of this article is a ready-to-copy skill library.
## SaaS web app starter pack
A SaaS web app harness needs to coordinate frontend, backend, tests, and UI verification.
It also needs stronger guardrails because features often cross auth, billing, data validation, and release surfaces.
Recommended skill folders:
```
.agent/SKILLS/
saas-spec-to-plan/
saas-implement-feature/
saas-browser-qa/
saas-regression-guard/
saas-release-notes/
```
.agent/SKILLS/saas-spec-to-plan/SKILL.md
```
name: saas-spec-to-plan
description: Turn a SaaS product request into an implementation plan covering frontend, backend, data, auth, and rollout risk.
triggers:
- "Plan this SaaS feature"
- "Break down this product spec"
- "Write implementation plan"
instructions:
1. Read `docs/TASK.md`.
2. Extract:
- user goal
- UI surface
- backend/API changes
- data model impact
- auth/permissions impact
- analytics/logging implications
3. Write `docs/PLAN.md` with:
- feature summary
- assumptions
- files likely affected
- ordered implementation steps
- risks and unknowns
- acceptance criteria
4. If auth, billing, or schema changes are involved, mark the plan as HIGH RISK.
5. Do not edit code.
```
.agent/SKILLS/saas-implement-feature/SKILL.md
```
name: saas-implement-feature
description: Implement an approved SaaS feature in small increments.
triggers:
- "Implement this SaaS feature"
- "Execute the approved plan"
instructions:
1. Read `docs/PLAN.md` and confirm approval.
2. Implement at most 3 steps per cycle.
3. For each step:
- update frontend and backend consistently
- preserve existing API contracts unless the plan says otherwise
- add or update tests
- add concise notes to `CHANGELOG.md`
4. After each cycle:
- run unit tests
- run integration tests if present
- summarize changed files and remaining work
5. Stop after the cycle and wait.
```
.agent/SKILLS/saas-browser-qa/SKILL.md
```
name: saas-browser-qa
description: Verify core SaaS UI flows in a browser.
triggers:
- "Check this in the browser"
- "Run SaaS QA"
- "Verify the UI flow"
instructions:
1. Start the app with the standard local command.
2. Open the relevant route in a browser.
3. Verify:
- page loads
- primary CTA works
- form validation works
- success state renders
- error state renders if possible
4. Inspect DOM and console for obvious issues.
5. Write results to `docs/QA.md`:
- tested route
- happy path result
- broken states
- console errors
- screenshots captured
```
.agent/SKILLS/saas-regression-guard/SKILL.md
```
name: saas-regression-guard
description: Expand tests around changed product areas to reduce regressions.
triggers:
- "Add regression coverage"
- "Guard this feature"
instructions:
1. Read recent entries in `CHANGELOG.md`.
2. Identify changed routes, handlers, and business rules.
3. Add focused tests for:
- previous happy path
- one invalid input
- one permission/auth case if relevant
4. Run the relevant test suites.
5. Append test summary to `docs/QA.md`.
```
.agent/SKILLS/saas-release-notes/SKILL.md
```
name: saas-release-notes
description: Prepare a clean product-facing and developer-facing release summary.
triggers:
- "Write release notes"
- "Prepare rollout notes"
instructions:
1. Read `CHANGELOG.md`, `docs/PLAN.md`, and `docs/QA.md`.
2. Write:
- user-facing release notes
- technical changes summary
- migration/setup notes
- rollback concerns
3. Save to `docs/RELEASE.md`.
```
## SaaS Example Run
A builder can now run a full feature loop like this.
1. Write a task in docs/TASK.md.
2. Prompt the Planner: “Use saas-spec-to-plan and write the implementation plan.”
3. Approve the plan manually.
4. Prompt the Implementer: “Use saas-implement-feature for the next 3 steps.”
5. Prompt the Verifier: “Use saas-browser-qa and then saas-regression-guard.”
6. Prompt the Release Assistant: “Use saas-release-notes.”
That is already a meaningful agent workflow.
It is file-based, reviewable, and reusable.
## CLI Tool Starter Pack
A CLI harness is different because the terminal is the product surface.
Good CLI agents need to think about commands, arguments, output formats, error messages, and exit codes, not browser flows.
Recommended skill folders:
```
.agent/SKILLS/
cli-spec-to-plan/
cli-command-implementer/
cli-fixture-validator/
cli-release-packager/
```
.agent/SKILLS/cli-spec-to-plan/SKILL.md
```
name: cli-spec-to-plan
description: Turn a CLI request into a command-oriented implementation plan.
triggers:
- "Plan this CLI feature"
- "Break down this command"
instructions:
1. Read `docs/TASK.md`.
2. Extract:
- command name
- input flags/options
- expected output
- exit codes
- error cases
- files/configs touched
3. Write `docs/PLAN.md` with:
- CLI contract
- example invocations
- step-by-step implementation
- test cases
4. Do not write code yet.
```
.agent/SKILLS/cli-command-implementer/SKILL.md
```
name: cli-command-implementer
description: Implement CLI commands with predictable UX and test coverage.
triggers:
- "Implement the CLI command"
- "Build this CLI feature"
instructions:
1. Read approved `docs/PLAN.md`.
2. Implement command behavior in small steps.
3. Ensure:
- help text exists
- invalid flags fail clearly
- stdout is reserved for intended output
- stderr is used for failures
- exit codes are meaningful
4. Add tests for:
- success case
- invalid input
- edge case
5. Update `CHANGELOG.md`.
```
.agent/SKILLS/cli-fixture-validator/SKILL.md
```
name: cli-fixture-validator
description: Validate CLI behavior using repeatable fixture inputs and output snapshots.
triggers:
- "Validate CLI behavior"
- "Run CLI QA"
instructions:
1. Create or use fixtures under `tests/fixtures/`.
2. Run the CLI against representative inputs.
3. Verify:
- output text
- structured output formatting if JSON
- error text
- exit status
4. Record findings in `docs/QA.md`.
```
.agent/SKILLS/cli-release-packager/SKILL.md
```
name: cli-release-packager
description: Prepare a CLI tool for shipping.
triggers:
- "Prepare CLI release"
- "Package this CLI"
instructions:
1. Ensure README usage examples are current.
2. Ensure `--help` text matches actual behavior.
3. Write install instructions, upgrade notes, and breaking changes to `docs/RELEASE.md`.
4. Include 3 copy-paste examples.
```
## CLI example prompt flow
- “Read docs/TASK.md and use cli-spec-to-plan.”
- “Implement the approved plan with cli-command-implementer.”
- “Run cli-fixture-validator and write the QA file.”
- “Run cli-release-packager and update docs.”
This section lands because it shows that agentic coding is not just for web apps.
The same harness pattern can drive a clean terminal product workflow.
## MCP server starter pack
MCP servers need an even stricter design discipline because the product is made of tools and schemas.
If the tool boundaries are vague, the whole system becomes hard to reason about.
Recommended skill folders:
```
.agent/SKILLS/
mcp-spec-to-plan/
mcp-tool-designer/
mcp-schema-validator/
mcp-example-client/
```
.agent/SKILLS/mcp-spec-to-plan/SKILL.md
```
name: mcp-spec-to-plan
description: Turn an MCP server idea into a tool-by-tool implementation plan.
triggers:
- "Plan this MCP server"
- "Break down these MCP tools"
instructions:
1. Read `docs/TASK.md`.
2. Extract:
- server purpose
- tools/resources/prompts to expose
- required auth
- external APIs/services
- failure modes
3. Write `docs/PLAN.md` with:
- server overview
- tool inventory
- input/output schema expectations
- transport/runtime decisions
- testing plan
4. Flag any missing auth or security assumptions.
```
.agent/SKILLS/mcp-tool-designer/SKILL.md
```
name: mcp-tool-designer
description: Implement MCP tools with strict boundaries and schemas.
triggers:
- "Implement MCP tools"
- "Build the MCP server"
instructions:
1. Read approved `docs/PLAN.md`.
2. For each tool:
- define a clear name
- define strict input schema
- define predictable output shape
- keep scope narrow
3. Avoid multi-purpose tools when two simpler tools would be clearer.
4. Add example payloads or fixtures for each tool.
5. Update `CHANGELOG.md`.
```
.agent/SKILLS/mcp-schema-validator/SKILL.md
```
name: mcp-schema-validator
description: Validate MCP tool schemas and behavior.
triggers:
- "Validate MCP schemas"
- "Test the MCP server"
instructions:
1. Check that each tool has:
- clear description
- required inputs
- sensible defaults
- explicit error responses
2. Run local calls or fixture-based invocations.
3. Verify schema compliance and output consistency.
4. Write findings to `docs/QA.md`.
```
.agent/SKILLS/mcp-example-client/SKILL.md
```
name: mcp-example-client
description: Produce copy-paste examples so users can actually use the MCP server.
triggers:
- "Write MCP usage examples"
- "Add client setup examples"
instructions:
1. Create a short setup section.
2. Add 3 example tool calls.
3. Add one failure-mode example.
4. Save to `docs/USAGE.md`.
```
## Why this matters
Most MCP content stays abstract.
A better builder article makes the point that schemas are part of product UX.
A narrow, well-described tool is better than a vague “do everything” tool because it is easier for both humans and agents to use correctly.
## Mobile app starter pack
A mobile harness is about screens, state transitions, navigation, and device behavior.
The challenge is not only whether the code compiles.
The challenge is whether the flow feels coherent across loading, success, error, permission, and retry states.
Recommended skill folders:
```
.agent/SKILLS/
mobile-spec-to-plan/
mobile-screen-implementer/
mobile-flow-qa/
mobile-state-guard/
.agent/SKILLS/mobile-spec-to-plan/SKILL.md
```
```
name: mobile-spec-to-plan
description: Turn a mobile product request into a screen-and-flow implementation plan.
triggers:
- "Plan this mobile feature"
- "Break down this app flow"
instructions:
1. Read `docs/TASK.md`.
2. Extract:
- target screens
- navigation changes
- state transitions
- permissions/device APIs involved
- loading/empty/error states
3. Write `docs/PLAN.md` with:
- screen inventory
- navigation flow
- component/state changes
- testing approach
4. Do not implement yet.
```
.agent/SKILLS/mobile-screen-implementer/SKILL.md
```
name: mobile-screen-implementer
description: Implement mobile app changes screen by screen.
triggers:
- "Implement mobile feature"
- "Build the mobile screens"
instructions:
1. Read approved `docs/PLAN.md`.
2. Implement one screen or flow segment at a time.
3. Ensure every screen includes:
- loading state
- empty state if relevant
- error state
4. Keep shared UI patterns consistent.
5. Add or update tests where possible.
6. Update `CHANGELOG.md`.
```
.agent/SKILLS/mobile-flow-qa/SKILL.md
```
name: mobile-flow-qa
description: Verify mobile flows with user-centric QA notes.
triggers:
- "Run mobile QA"
- "Verify the app flow"
instructions:
1. Launch the app or preview.
2. Walk the primary user path.
3. Verify:
- first screen clarity
- primary CTA visibility
- back navigation behavior
- keyboard/input behavior
- permission prompt behavior if relevant
4. Write findings to `docs/QA.md`.
```
.agent/SKILLS/mobile-state-guard/SKILL.md
```
name: mobile-state-guard
description: Protect mobile app quality by hardening states and transitions.
triggers:
- "Harden mobile states"
- "Check loading and error states"
instructions:
1. Read recent changes from `CHANGELOG.md`.
2. For impacted screens, verify:
- loading state exists
- empty state exists where needed
- error state is actionable
- navigation cannot dead-end the user
3. Add missing state handling.
4. Update `docs/QA.md`.
```
## The mobile lesson
Some products are not test-heavy in the same way as backend systems.
So the harness has to force state quality and flow quality explicitly.
## How to run this in practice
The article should not stop at file dumps.
Builders need to see how the loop feels in real use.
A minimal operator workflow looks like this.
Step 1: Write the task
Create docs/TASK.md and describe one real feature.
Step 2: Ask for a plan
Prompt:
```
Read `docs/TASK.md`. Use the correct planning skill for this project type. Write a detailed implementation plan to `docs/PLAN.md`. Do not edit code yet.
```
Step 3: Approve the plan
The human edits the plan, narrows scope if necessary, and marks it approved.
Step 4: Implement in chunks
Prompt:
```
Use the correct implementation skill. Execute the next 3 approved steps from `docs/PLAN.md`. Update tests and `CHANGELOG.md`. Stop after the chunk and summarize what changed.
```
Step 5: Verify
Prompt:
```
Use the relevant verification skill for this project type. Write results to `docs/QA.md`. Highlight broken states, regressions, or missing coverage.
```
Step 6: Prepare release notes
Prompt:
```
Use the release skill. Read the plan, QA notes, and changelog. Write release notes and rollout notes.
```
This gives the reader a copy-paste control loop they can actually use with any competent coding agent that can read and write files, run commands, and follow instructions.
## Why this works better than prompt-only workflows
Three things improve immediately.
First, the agent stops improvising its entire operating model on every task.
The repo now contains the operating model in durable files.
Second, the builder gets better observability.
Instead of wondering what happened, the builder can inspect TASK.md, PLAN.md, QA.md, RELEASE.md, and CHANGELOG.md to see exactly how the work progressed.
Third, the workflow becomes transferable.
Once the harness exists, it can be copied from one repo to another, extended with new skills, and adapted for different product categories without rethinking the whole system each time.
## What to tell readers to do this week
The easiest way to get adoption is to give builders a short setup path.
- Pick one real project.
- Add the .agent/ folder and AGENTS.md.
- Add the skill files for the relevant product type.
- Create docs/TASK.md, docs/PLAN.md, and docs/QA.md.
- Run one real feature through the loop.
- Keep the feature small enough to finish in one sitting.
- Compare the result to the usual chat-based workflow.
## Final point
The future of builder workflows is probably not one giant autonomous agent that does everything perfectly.
It is more likely a compact harness where humans steer, agents execute, and the repo itself becomes the control plane.
That is good news for builders.
A useful agent workflow does not start with a new foundation model.
It starts with a folder, a few Markdown files, a clean loop, and the discipline to make the system repeatable.
## 相关链接
- [Avid](https://x.com/Av1dlive)
- [@Av1dlive](https://x.com/Av1dlive)
- [21K](https://x.com/Av1dlive/status/2058951175236727025/analytics)
- [May 16](https://x.com/Av1dlive/status/2055337557140046242)
- [Paid partnership](https://help.x.com/rules-and-policies/paid-partnerships-policy)
- [1.9K](https://x.com/Av1dlive/status/2055337557140046242/analytics)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [12:39 AM · May 26, 2026](https://x.com/Av1dlive/status/2058951175236727025)
- [21.3K Views](https://x.com/Av1dlive/status/2058951175236727025/analytics)
- [View quotes](https://x.com/Av1dlive/status/2058951175236727025/quotes)
---
*导出时间: 2026/5/26 12:26:00*
---
## 中文翻译
# 如何在 2026 年使用 AI 交付你的首款产品（构建者指南）
**作者**: Avid
**日期**: 2026-05-15T17:20:34.000Z
**来源**: [https://x.com/Av1dlive/status/2058951175236727025](https://x.com/Av1dlive/status/2058951175236727025)
---
AI 每周都在制造百万富翁。
我今年正使用 AI 交付产品。
这就是我学到的经验，以及你如何入门。
## 为什么这很重要
我正在交付一个 SaaS 平台。
我已经交付了一个 MCP 服务器和一个获得 2000 星的 GitHub 仓库。
我也正在交付一个 iOS 移动应用。
最后，我还为你提供了工作流文件。如果你正在构建 MCP 服务器、SaaS Web 应用、iOS 移动应用或任何移动应用，这些是你可以在一个单一流程中用来完成所有工作的技能文件和工作流。
> **Avid@Av1dlive**: [原文链接](https://x.com/Av1dlive/status/2055337557140046242)
>
> 今天别再刷 Tinder 了
> 我为初创公司创始人做了一个 Tinder，花了我不到一个小时
> 滑动你所在领域的创始人。匹配。获取破冰话题。毫无尴尬地发私信。
> 像 SuperappAI 这样的应用让构建 iOS 应用变得非常简单。
>
> 
# 简介
大多数人使用 AI 编码工具时，仅仅将其视为更聪明的自动补全。
这对于微小的任务尚可。
一旦工作变成多步骤、有状态，或者分散在前端、后端、测试、文档和发布说明中，这种方式就会失效。
真正的转变不仅仅是使用更好的模型。
转变在于将模型封装在一个由指令、工具、文件和验证组成的可重复系统中，使其像可靠的软件操作员一样工作，而不是混乱的聊天会话。
这个系统就是“harness”（控制束/框架）。
这篇文章是为构建者准备的实战手册。
它展示了如何在一个仓库内部设置轻量级的代理框架，如何构建 AGENTS.md，如何定义可重用的技能文件，以及该设置应如何根据你是构建 SaaS Web 应用、CLI 工具、MCP 服务器还是移动应用而变化。
目标很简单。
将模糊的“使用代理”建议转化为真正帮助人们交付产品的工作流。
## 为什么大多数人用不好代理
常见的失败模式很明显。
构建者打开一个 AI 编码工具，粘贴功能需求，看着它编辑十二个文件，然后花一个小时清理烂摊子。
问题通常不仅仅在于模型。
问题在于代理没有被给予结构，除了提示词之外没有记忆，没有停止条件，也没有真正的方法来验证结果是否确实正确。
这意味着正确的问题不再是“我应该使用什么提示词？”
正确的问题是“我应该构建什么样的环境，以便代理能安全、渐进且可验证地工作？”
## 所谓的 Harness 到底是什么
一个有用的 Harness 有五个部分。
- 代理可以读取和修改的工作目录。
- 一组持久化的指令，存在于文件中，而不仅仅是在聊天记录中。
- 用于重复工作流的小型可重用技能库。
- 由测试、QA 步骤和输出制品组成的验证层。
- 停止并检查的循环，以便人类保持控制权。
对于构建者来说，这就足够了。
你不需要企业级基础设施。
你不需要自定义编排服务器。
你不需要研究实验室的预算。
你需要的是一个干净的仓库结构和清晰的操作规则。
这是最基础的布局。
```
project/
.agent/ # 代理用来操作的一切
AGENTS.md # 全局规则、角色、护栏和停止条件
SKILLS/ # 用于重复工作流的可重用操作手册
spec-to-plan/
SKILL.md # 将任务或规格转化为有序的实现计划
implementation/
SKILL.md # 告诉代理如何以小块形式执行批准的工作
verification/
SKILL.md # 定义如何测试、检查和验证结果
release/
SKILL.md # 准备发布说明、迁移说明和交接文档
docs/ # 你和代理之间共享的工作记忆
TASK.md # 原始任务、规格或功能请求
PLAN.md # 编码开始前生成的分步计划
QA.md # 验证笔记、发现的 Bug、截图和测试结果
RELEASE.md # 最终发布摘要、推出说明和升级指南
tests/ # 你的安全网；单元测试、集成测试或 fixture 测试位于此处
CHANGELOG.md # 跨迭代的有意义变更的运行日志
README.md # 面向人类的设置、使用和项目上下文
```
这种结构将记忆和流程外部化了。
代理不再试图将所有内容保存在一个巨大的提示词中，而是在正确的时间读取正确的文件，并将其输出写回仓库。
这就是核心思想。
## 核心循环
本文中的每种产品类型都使用相同的循环。
1. 在 docs/TASK.md 中写下任务。
2. 要求代理将其转换为 docs/PLAN.md 中的计划。
3. 审查并批准计划。
4. 让代理实现一小块。
5. 运行验证。
6. 撰写 QA 报告。
7. 准备发布说明或下一步行动。
一个好的 TASK.md 简单且具体。
```
TASK
为产品添加电子邮件和密码登录。
Requirements:
- 保持现有的 OAuth 登录正常工作。
- 添加前端表单验证。
- 添加后端 auth 端点。
- 添加成功和失败登录的测试。
- 不要更改计费流程。
```
规划器将其转换为基于文件的计划。
人类根据需要编辑计划。
只有在批准后，实施者才开始编写代码。
## 每个仓库都应该有的一个文件
每个仓库都应该有一个基础合约，定义代理的工作方式。
这个文件是随机编辑和可预测操作之间的区别。
将此粘贴到 .agent/AGENTS.md 中。
```
# AGENTS.md
## Mission
通过可重复循环将产品规格转化为可工作的软件：
spec -> plan -> implementation -> verification -> release prep。
## Global rules
- 在将计划写入 `docs/PLAN.md` 之前，切勿开始编码。
- 在停止审查之前，切勿实施超过 3 个计划步骤。
- 在完成有意义的工作后，始终更新 `CHANGELOG.md`。
- 优先使用代码库中的现有模式，而不是发明新的抽象。
- 如果任务涉及身份验证、付款、数据库迁移、生产基础设施或破坏性操作，请在继续之前停止并请求批准。
- 如果不确定，请缩小范围而不是猜测。
- 保持输出简洁、结构化并基于文件。
## Standard loop
1. 读取 `docs/TASK.md`
2. 撰写 `docs/PLAN.md`
3. 等待批准
4. 小块实施
5. 运行相关验证
6. 撰写 `docs/QA.md`
7. 总结下一步行动
## Required artifacts
- `docs/PLAN.md`
- `docs/QA.md`
- `CHANGELOG.md`
## Roles
### Planner
将规格转化为带有风险、触及文件和验收标准的实施计划。
### Implementer
执行批准的计划步骤，编写代码，添加测试并更新 changelog。
### Verifier
运行检查，审查输出并撰写 QA 笔记。
### Release Assistant
准备发布说明、设置文档、迁移说明和操作交接。
## Stopping conditions
在以下情况停止并升级：
- 测试反复失败
- 同一操作循环两次
- 缺少必要的上下文
- 任务需要密钥或生产凭据
```
该文件为代理提供了持久的操作合约。
它还给了构建者更重要的东西。
一种在出错时推理代理行为的方法。
## 一套框架，四种产品类型
框架骨架在产品之间保持不变。
改变的是实施和验证的含义。
这是关键思想。
框架不是一个神奇的提示词。
它是一个适应产品表面的可重复操作模型。
## 技能文件才是真正的工作流
技能文件是一个小型程序文档，告诉代理如何执行某种重复性的工作。
对于构建者来说，技能文件做三件事。
- 它们减少重复提示。
- 它们标准化输出结构。
- 它们让同一个仓库能够干净地支持多种产品工作流。
本文的其余部分是一个现成可复制的技能库。
## SaaS Web 应用入门包
SaaS Web 应用框架需要协调前端、后端、测试和 UI 验证。
它还需要更强的护栏，因为功能通常跨越身份验证、计费、数据验证和发布表面。
推荐的技能文件夹：
```
.agent/SKILLS/
saas-spec-to-plan/
saas-implement-feature/
saas-browser-qa/
saas-regression-guard/
saas-release-notes/
```
.agent/SKILLS/saas-spec-to-plan/SKILL.md
```
name: saas-spec-to-plan
description: 将 SaaS 产品请求转化为实施计划，涵盖前端、后端、数据、身份验证和推出风险。
triggers:
- "Plan this SaaS feature"
- "Break down this product spec"
- "Write implementation plan"
instructions:
1. 读取 `docs/TASK.md`。
2. 提取：
- user goal
- UI surface
- backend/API changes
- data model impact
- auth/permissions impact
- analytics/logging implications
3. 撰写 `docs/PLAN.md`，包含：
- feature summary
- assumptions
- files likely affected
- ordered implementation steps
- risks and unknowns
- acceptance criteria
4. 如果涉及身份验证、计费或架构变更，请将计划标记为 HIGH RISK。
5. 不要编辑代码。
```
.agent/SKILLS/saas-implement-feature/SKILL.md
```
name: saas-implement-feature
description: 以小增量实施已批准的 SaaS 功能。
triggers:
- "Implement this SaaS feature"
- "Execute the approved plan"
instructions:
1. 读取 `docs/PLAN.md` 并确认已批准。
2. 每个周期最多实施 3 个步骤。
3. 对于每个步骤：
- 一致地更新前端和后端
- 保留现有的 API 契约，除非计划另有说明
- 添加或更新测试
- 向 `CHANGELOG.md` 添加简洁的笔记
4. 每个周期后：
- 运行单元测试
- 如果存在，运行集成测试
- 总结更改的文件和剩余工作
5. 在周期结束后停止并等待。
```
.agent/SKILLS/saas-browser-qa/SKILL.md
```
name: saas-browser-qa
description: 在浏览器中验证核心 SaaS UI 流程。
triggers:
- "Check this in the browser"
- "Run SaaS QA"
- "Verify the UI flow"
instructions:
1. 使用标准本地命令启动应用。
2. 在浏览器中打开相关路由。
3. 验证：
- page loads
- primary CTA works
- form validation works
- success state renders
- error state renders if possible
4. 检查 DOM 和控制台是否存在明显问题。
5. 将结果写入 `docs/QA.md`：
- tested route
- happy path result
- broken states
- console errors
- screenshots captured
```
.agent/SKILLS/saas-regression-guard/SKILL.md
```
name: saas-regression-guard
description: 围绕更改的产品区域扩展测试以减少回归。
triggers:
- "Add regression coverage"
- "Guard this feature"
instructions:
1. 读取 `CHANGELOG.md` 中的最近条目。
2. 识别更改的路由、处理程序和业务规则。
3. 为以下内容添加专注的测试：
- 之前的 happy path
- 一个无效输入
- 一个权限/身份验证案例（如果相关）
4. 运行相关的测试套件。
5. 将测试摘要附加到 `docs/QA.md`。
```
.agent/SKILLS/saas-release-notes/SKILL.md
```
name: saas-release-notes
description: 准备干净的面向产品和面向开发人员的发布摘要。
triggers:
- "Write release notes"
- "Prepare rollout notes"
instructions:
1. 读取 `CHANGELOG.md`、`docs/PLAN.md` 和 `docs/QA.md`。
2. 撰写：
- user-facing release notes
- technical changes summary
- migration/setup notes
- rollback concerns
3. 保存到 `docs/RELEASE.md`。
```
## SaaS 示例运行
构建者现在可以像这样运行完整的功能循环。
1. 在 docs/TASK.md 中写下任务。
2. 提示规划器：“Use saas-spec-to-plan and write the implementation plan.”
3. 手动批准计划。
4. 提示实施者：“Use saas-implement-feature for the next 3 steps.”
5. 提示验证者：“Use saas-browser-qa and then saas-regression-guard.”
6. 提示发布助手：“Use saas-release-notes.”
这已经是一个有意义的代理工作流了。
它是基于文件的、可审查的且可重用的。
## CLI 工具入门包
CLI 框架是不同的，因为终端就是产品表面。
优秀的 CLI 代理需要考虑命令、参数、输出格式、错误消息和退出代码，而不是浏览器流程。
推荐的技能文件夹：
```
.agent/SKILLS/
cli-spec-to-plan/
cli-command-implementer/
cli-fixture-validator/
cli-release-packager/
```
.agent/SKILLS/cli-spec-to-plan/SKILL.md
```
name: cli-spec-to-plan
description: 将 CLI 请求转化为面向命令的实施计划。
triggers:
- "Plan this CLI feature"
- "Break down this command"
instructions:
1. 读取 `docs/TASK.md`。
2. 提取：
- command name
- input flags/options
- expected output
- exit codes
- error cases
- files/configs touched
3. 撰写 `docs/PLAN.md`，包含：
- CLI contract
- example invocations
- step-by-step implementation
- test cases
4. 暂时不要编写代码。
```
.agent/SKILLS/cli-command-implementer/SKILL.md
```
name: cli-command-implementer
description: 使用可预测的 UX 和测试覆盖率实施 CLI 命令。
triggers:
- "Implement the CLI command"
- "Build this CLI feature"
instructions:
1. 读取已批准的 `docs/PLAN.md`。
2. 分步实施命令行为。
3. 确保：
- help text exists
- invalid flags fail clearly
- stdout is reserved for intended output
- stderr is used for failures
- exit codes are meaningful
4. 为以下内容添加测试：
- success case
- invalid input
- edge case
5. 更新 `CHANGELOG.md`。
```
.agent/SKILLS/cli-fixture-validator/SKILL.md
```
name: cli-fixture-validator
description: 使用可重复的 fixture 输入和输出快照验证 CLI 行为。
triggers:
- "Validate CLI behavior"
- "Run CLI QA"
instructions:
1. 在 `tests/fixtures/` 下创建或使用 fixture。
2. 针对代表性输入运行 CLI。
3. 验证：
- output text
- structured output formatting if JSON
- error text
- exit status
4. 在 `docs/QA.md` 中记录发现。
```
.agent/SKILLS/cli-release-packager/SKILL.md
```
name: cli-release-packager
description: 准备 CLI 工具以供发布。
triggers:
- "Prepare CLI release"
- "Package this CLI"
instructions:
1. 确保 README 使用示例是最新的。
2. 确保 `--help` 文本与实际行为匹配。
3. 将安装说明、升级说明和重大更改写入 `docs/RELEASE.md`。
4. 包含 3 个复制粘贴示例。
```
## CLI 示例提示流程
- “Read docs/TASK.md and use cli-spec-to-plan.”
- “Implement the approved plan with cli-command-implementer.”
- “Run cli-fixture-validator and write the QA file.”
- “Run cli-release-packager and update docs.”
本节之所以成功，是因为它表明代理编码不仅适用于 Web 应用。
相同的框架模式可以驱动干净的终端产品工作流。
## MCP 服务器入门包
MCP 服务器需要更严格的设计纪律，因为产品是由工具和架构组成的。
如果工具边界模糊，整个系统就很难推理。
推荐的技能文件夹：
```
.agent/SKILLS/
mcp-spec-to-plan/
mcp-tool-designer/
mcp-schema-validator/
mcp-example-client/
```
.agent/S