SaaSAllTheThings：AI Agent 工具实践指南

工作中遇到相关需求时，SaaSAllTheThings值得先读说明，因为它主要用于从头开始构建 B2B SaaS，或者使用 AI 助手将概念验证或现有应用程序转变为 Azure 上成熟的多租户 SaaS：您拥有产品。实际做日常自动化时，经常会碰到输入边界、依赖和失败处理如果不清楚就很难稳定复用，所以功能列表并不能代替验证。落地前可以用一项范围明确的真实任务完成最小试跑，用配置时间、输出质量、异常信息和维护痕迹判断它是否真的省事。我的判断是，它更适合愿意先做小范围验证并复查原始文档的团队；若眼下没有这类需求，先保留观察即可。

SaaSAllTheThings

从头开始构建 B2B SaaS，或者将工作概念证明或现有应用程序转变为成熟、现代的 SaaS，并由 AI 助理进行构建。

两个起点，一个目的地：一种多租户产品，企业客户使用自己的身份提供商登录，按照您定义的计划，连接到他们已经运行的系统，在事件驱动的 Azure 后端上，该后端保持便宜，但规模较小，并随着使用而增长。

• 从头开始：简短的产品访谈，然后以经过验证的小步骤构建平台，从租赁和登录开始，而不是稍后将其固定。
• 从概念验证或现有应用程序： 首先进行评估（准备情况、路线图、要举办的研讨会），然后将应用程序在测试后逐个区域移动，同时保持运行。

您拥有该产品：它能做什么、为谁服务、以什么顺序。该框架拥有该架构并强制执行：事件驱动的 Azure Functions 后端、独立的 Windows 和移动客户端、使用联合身份登录的 OIDC、稍后可以将客户转移到自己的部署的池化多租户，以及从 Navision 开始的企业集成（Dynamics NAV / Business Central）。 AI 在该架构中构建、测试并保存记录。专为 Claude Code 打造，可与任何读取 AGENTS.md 的 AI 编码助手一起使用。所有内容都位于您应用程序自己的 git 存储库中。

在您的应用程序中，其简称为 .satt/ (SaaS All The Things)，设置命令为 /saasallthethings:saas-all-the-things。

为什么

AI 后端代码编写速度快。如果没有结构，速度就会以熟悉的方式出错：

• 架构被侵蚀。 一个处理程序从标头读取租户，另一个处理程序从客户端调用数据库，第三个处理程序存储连接字符串。通过 SaaSAllTheThings，参考架构由框架拥有并经过机器检查。唯一的偏离方法是您接受 ADR，并且仅当接受的 ADR 命名时，检查才会接受异常。
• 产品漂移。 AI悄悄决定了一个你从未同意的商业规则。产品电话会向您提供 2-4 个选项以及建议。只有你的选择会被写下来，任何未决定的事情都会出现在开放问题列表中，而不是被猜测。
• “完成”意味着“已编译”。 一项检查定义“有效”：架构规则成立，构建通过并且测试通过。它在每次涉及代码的提交之前运行，在克劳德代码中也在 AI 结束其回合之前运行。
• 保留单租户习惯。 特定于租户的 ifs，从请求中获取的租户 ID，随着每个客户的增长而增长的云。前两个检查失败，成本默认值（无服务器、消耗）涵盖第三个。
• 会话之间的上下文会丢失。 一些普通文件包含所有内容：产品文档、决策日志、ADRs、集成合同、任务队列和架构表。每个事实都有一个家，因此任何会话都会从上一个事实停止的地方开始。

三大原则

• 低成本。 在令牌中：一个小的始终加载的核心，仅在使用时加载的过程和参考主题，在新的上下文中构建。在 Azure 中：Flex 消费功能、无服务器 Cosmos DB、一个服务总线命名空间、日志上限和预算。任何更大的东西都需要 ADR。
• 小迭代。 一项，一次提交。商品尺寸有 S、M 或 L，L 商品是分开的。端到端工作的垂直切片一次构建一个层。计划最多提前一个阶段。
• 许多文件。 每个文件一种类型，每个文件一个函数，每个用例一个处理程序，每个资源一个 Bicep 模块，每个文件一个参考主题。超过大小限制的源文件检查失败。

如何使用

首先评估（可选）

还不确定需要什么？ saas-assessment 技能在不更改现有应用程序的情况下分析现有应用程序，并编写一份报告：应用程序的准备程度（评分，有证据）、粗略努力的分阶段开发路线图、要做出的决策以及要举办的研讨会，每个研讨会都有参与者、准备工作、定时议程和方法。它首先询问您的堆栈首选项。安装如下技能（它随插件一起提供，或 npx skills add Freakling/SaaSAllTheThings），然后询问“如何使这个应用程序成为 SaaS？”。研讨会的笔记和报告将在随后的入职培训中提供，因此无需重复询问。

随时随地进行设计会议

架构和产品决策、集成合同和研讨会不需要终端。 saas-design-session 技能可以在 Claude Code、Cowork 或 Claude 应用程序（Web、桌面、移动）中运行它们，无论有或没有应用程序的存储库。它带有参考架构和研讨会手册，因此它按照与其他所有内容相同的规则进行论证：带有建议的选项，首先遵守参考，您决定。

询问诸如“我们应该使用哪个数据存储？”、“Navision 应该拥有什么？”、“准备集成研讨会”或“记录这个研讨会”之类的问题。它准备议程和预读，在研讨会期间记录时间和记录决策，并以笔记结束每次会议，包括用于架构决策的 ADR 草稿。在您的存储库之外，您可以下载笔记。将它们放入应用程序的 assessment/workshops/ 中，然后在 Claude Code 中“处理研讨会笔记”将它们转换为记录（如果尚未安装 SaaSAllTheThings，则入职会将其转换为记录）。在安装了 SaaSAllTheThings 的应用程序中，该技能通过应用程序自己的程序自行写入记录。

安装

您的应用程序需要 git（如果没有，则为 git init）并且没有未提交的更改。您还需要 bash（在 Windows 上，它附带了适用于 Windows 的 Git）和后端堆栈的工具链：默认为 .NET SDK 8+。

选项 1：Claude Code 插件。 在 Claude Code 中：

/plugin marketplace add Freakling/SaaSAllTheThings
/plugin install saasallthethings@saasallthethings

然后在应用程序的文件夹中打开一个新的 Claude Code 会话（或运行 /reload-plugins），并运行 /saasallthethings:saas-all-the-things。

选项 2：手动安装。 将此存储库作为名为 SaaSAllTheThings 的文件夹放在应用程序的根文件夹中：在其中运行 git clone https://github.com/Freakling/SaaSAllTheThings.git SaaSAllTheThings，或下载 zip 并重命名提取的文件夹。然后问你的助理：

阅读 SaaSAllTheThings/ONBOARDING.md 并按照其将 SaaSAllTheThings 安装到该项目中。

选项3：技能CLI（任何读取技能的助手）：

npx skills add Freakling/SaaSAllTheThings

然后让你的助手在你的应用程序文件夹中输入“SaaS all the things”。该技能将此存储库的匹配版本克隆到应用程序外部的临时文件夹中，并从那里遵循 ONBOARDING.md 。

无论哪种方式，入职都会确定这是新应用程序、现有应用程序还是升级。然后它：

1. 安装文件；
2. 与您一起解决后端堆栈：对于现有应用程序，它会询问您的偏好，如果兼容，则保留您的堆栈，否则列出兼容的堆栈；
3. 采访您（新应用程序）或阅读现有应用程序，包括其单租户习惯和秘密；
4. 将路线图的第一阶段SaaS写入TASKS.md；
5. 以一项供您批准的提交结束。

然后，重新启动 Claude Code，以便加载新命令。稍后该应用程序的每个新克隆都需要一个命令：bash tools/setup-clone.sh。

使用另一个 AI 助手： 告诉 onboarding，它仅安装工具中立核心 (--tools none)。您的助手读取 AGENTS.md，这将其指向 .satt/rules.md 和过程。检查和 git hook 对于每个工具和您来说都是相同的。

升级

• 插件：运行 /plugin marketplace update saasallthethings，然后运行 /plugin update saasallthethings@saasallthethings。在应用程序中启动新会话并再次运行 /saasallthethings:saas-all-the-things。
• 手动：将新的SaaSAllTheThings文件夹放入应用程序中，并再次请求ONBOARDING.md。
• 技能CLI：再次运行npx skills add Freakling/SaaSAllTheThings，然后要求升级。

仅替换框架自己的文件，并保留您对它们的编辑。当新版本也更改了您编辑的文件时，新版本会在其旁边写入 <file>.satt-new 供您合并。

日复一日

you, a customer or a pilot has an idea
        │
        ▼
product session ── options + a recommendation ── you decide ──► PRD + decisions.md + TASKS.md items
        │                                       architecture call? ──► /architect ──► ADR you accept
        ▼
next task ── builds the next ready item ── tests ── bash tools/check.sh ──► commit (you approve)
        │
        ▼
acceptance check (does each built rule work?)  ·  feedback (does it help the customer?)
        │
        ▼
bugs and product proposals ── you decide ── repeat

这是什么

谁做什么

您的应用程序中安装了什么

your-app/
│  yours: never overwritten
├── AGENTS.md                   for every assistant: project facts, layout, architecture table, project rules
├── CLAUDE.md                   "@AGENTS.md", for Claude Code
├── TASKS.md                    milestones (the SaaSAllTheThings stages) and the queue (tasks and bugs)
├── product/prd.md              the product's current requirements, and Open Questions
├── product/decisions.md        why: one line per product decision
├── adr/                        architecture decision records: choices and accepted deviations
├── integrations/<system>/      one contract per external system (written by /integrate)
├── assessment/                 assessment reports and workshop notes (written by /assess)
├── validation/TEMPLATE.md      the feedback template, one section per capability
├── tools/check.cfg             the stack, the layers' folders, size limits
│
│  the framework's, tool-neutral: updated on upgrade
├── .satt/rules.md              the workflow rules, loaded through AGENTS.md
├── .satt/reference/            the reference architecture, one topic per file (the authority)
├── .satt/procedures/           next-task · build · assess · roadmap · product · architect · integrate ·
│                               tenant · acceptance · feedback · release · align · prune · review
├── .satt/templates/            ADR, integration contract and assessment templates
├── .satt/workshops/            the workshop playbook: one file per workshop, agendas and methods
├── .satt/tasks.md              the TASKS.md item format
├── tools/check.sh, archcheck.awk, cfg.sh, stacks/   the check, and one profile per backend stack
├── tools/setup-clone.sh        per clone: toolchain, dependencies, the pre-commit hook
├── .githooks/pre-commit        runs the check before commits that touch more than docs
├── validation/README.md        how acceptance checks and feedback reports work
│
│  the framework's, Claude Code adapter: updated on upgrade
├── .claude/skills/             /next-task and the rest: each points to its procedure
├── .claude/agents/             builder (builds each item in a fresh context) · reviewer (read-only)
├── .claude/hooks/              runs the check before a turn ends; blocks risky git and Azure commands;
│                               asks you before framework files change or an ADR is accepted
└── .claude/settings.json       permissions, hooks, timeouts

机器本地和 gitignored：.satt/state/（检查日志和缓存）和 .claude/settings.local.json。

The architecture, briefly

完整参考位于 .satt/reference/，每个文件一个主题；助理会读出某个项目涉及的主题。

• 层：合同、域、应用程序、基础设施、集成、主机、平台、客户端。每个可能仅依赖于 layers.md 列表。领域是纯粹的；主机（Azure Functions）很薄。
• 事件驱动：队列上的命令、主题上的事件（服务总线）、状态及其事件通过发件箱、幂等消费者、版本化合约保存在一起。
• 租赁： 集中。租户来自经过验证的令牌，而不是来自请求；每条记录和信息都携带着它；租户的不同之处在于注册表数据，而不是代码。租户可以稍后迁移到自己的部署。
• 身份： OIDC 和 Entra ID（多租户，因此客户使用自己的目录登录；对于没有目录的客户，使用外部 ID）。客户端使用带有 PKCE 的授权码。无处不在的托管身份和联合凭证：代码、配置或应用程序中没有秘密。
• 客户端： Windows 应用程序和移动应用程序，独立且精简。它们仅依赖于合同；每个人的 UI 技术都是 ADR。
• 集成： 每个外部系统一个反腐败层和功能应用程序，您决定的合同（方向、记录系统、冲突），测试中没有网络调用。
• 成本： 无服务器和消耗 SKUs、日志上限、每个环境的预算。

规则，简要说明

完整的规则位于 .satt/rules.md 中，助手每次都会阅读它们。

• 您决定产品。 助手提供选项和建议，本身从不回答开放性问题，并将未决定的值标记为 PLACEHOLDER。
• 框架决定架构。 不符合要求的构建会停下来询问；偏差为 ADRs 您接受。
• 每个事实都存在于一个地方，并在使其不真实的同一更改中进行更新。
• 完成意味着检查通过，并且只有在您批准的情况下才能进行工作。
• 受保护的命令： 在克劳德代码中，强制推送、reset --hard、--no-verify、删除 Azure 资源、读取 Key Vault 机密和创建客户端机密均被挂钩阻止。部署和云更改首先会询问您。

上下文和令牌使用

设计者（主会话）和开发者（构建者子代理）是故意分开的上下文。每个优化都不同。

主要会议——设计师和协调者

• 开始时很小。 会话以 AGENTS.md 和 .satt/rules.md (~10 KB) 开始。每个过程和每个参考主题仅在有项目触及时加载。
• 跨项目保持较小规模。 主会话选择项目、记录决策、更新 TASKS.md 并批准提交。它从不读取正在更改的文件。将项目交给构建器并且报告返回后，其上下文仅保存约 20 行的报告，而不是源文件、测试输出或检查日志。
• 会话之间无需传递任何内容。 TASKS.md、提交、AGENTS.md、PRD 和 ADRs 保存所有内容。一旦提交了某个项目，新会话（或克劳德代码中的 /clear）就不会丢失任何内容。构建过程中中断的项目会在 TASKS.md 中得到一行 Note:；下一个会话将读取它并继续。
• 设计会议：每次提交后都清晰。 一旦产品或架构会议的提交落地，对话就不再有价值——每个决定都在 PRD、decisions.md 和 ADRs 中。 /clear 在下一个主题之前。该程序会在每次会话结束时提醒您。

构建器子代理 - 具有新上下文的开发人员

• 每个项目都有新的上下文。 在 Claude Code 中，每个构建都作为一个单独的 builder 子代理运行，该子代理以空上下文开头。它仅读取项目所需的内容：Touches 中的文件、相关的 AGENTS.md 行、项目中命名的 PRD 部分以及工作涉及的参考架构主题。它构建、运行检查并返回约 20 行的结构化报告。
• 隔离防止累积。 由于构建器是隔离的，因此主会话永远不会携带文件内容、检查日志或编辑历史记录。完成十个项目的会议与完成一项的会议一样精简。
• 报告是唯一的渠道。 构建器的报告字段（Files、Systems、Contracts、Found、For the human）为主会话提供了更新记录并决定下一步的确切信息，仅此而已。

审阅者子代理 - 只读，也隔离

• 对于涉及合同、租户隔离、身份或存储模式的 L 或 XL 项目以及 M 项目，单独的 reviewer 子代理在提交之前会在其自己的新上下文中检查差异。调查结果以排名列表的形式返回主会议；代码结果被重建，超出范围的结果成为新的 TASKS.md 项目。

平行会议（设计+编码）

• 两个会话可以同时针对单独的 git 工作树运行——一个是设计，一个是构建。每个都从相同的项目文件中读取，并且 TASKS.md 中的 in-progress 声明阻止它们接触相同的项目。

sequenceDiagram
    participant H as You
    participant M as Main session (designer/orchestrator)
    participant B as Builder subagent (fresh context)
    participant Rev as Reviewer subagent (fresh context)
    participant R as Git records (TASKS.md, commits, PRD, ADRs)

    Note over M: starts with AGENTS.md + rules (~10 KB), loads procedures lazily

    H->>M: /next-task
    M->>R: grep candidates, read item
    M->>R: claim item as in-progress
    M->>+B: item ID and full text
    Note over B: reads Touches, Architecture rows, PRD sections, reference topics
    B->>B: build, then run check.sh
    B-->>-M: ~20-line report
    Note over M: keeps only the report — not source files, test output or check logs

    opt L/XL item, or M item touching contracts/isolation/identity/schema
        M->>R: git diff to review.diff
        M->>+Rev: item ID, report, check result
        Rev-->>-M: ranked findings
        M->>+B: rebuild with findings
        B-->>-M: updated report
    end

    M->>R: mark done, update TASKS.md and AGENTS.md
    M->>H: approve commit?
    H->>M: approved
    M->>R: commit

    Note over R: records are the handoff — /clear or a new session loses nothing

模型尺寸（推荐）：XS 和 S 项目在最小的可用模型上运行构建器（克劳德代码中的俳句）； M 到 XL 使用会话模型。入职要求您选择；记录在AGENTS.md › 项目规则中。

支票

bash tools/check.sh运行四个步骤：

1. 架构规则（tools/archcheck.awk）：层、纯域、仅来自令牌的租户、没有特定于租户的代码、没有秘密、版本化事件和命令、文件大小、Bicep 中的成本 SKUs；
2. 后端堆栈的构建和测试（tools/stacks/<stack>.sh：dotnet、typescript、python 或无）；
3. 安装 Bicep CLI 时，infra/ 中的 Bicep 文件；
4. tools/check.local.sh，如果应用程序有一个（客户端构建、模拟器测试）。

bash tools/check.sh --architecture 在几秒钟内单独运行步骤 1，无需工具链。检查通过时退出 0，失败时退出 1，无法运行时退出 3。它从不调用 Azure、网络或外部系统，并记住最后一次传递的状态，因此挂钩不会在没有任何更改时重新运行它。

定制

• 工作流规则对于一个应用程序来说是不同的，位于 AGENTS.md › 项目规则中，它们在其中胜过默认值。
• 一个应用程序的不同的 架构 位于 ADR (/architect) 中。它的 Exception: 行是唯一可以原谅检查失败的内容。
• 框架本身：编辑framework/（已安装文件）或project/（新应用程序的种子），将更改添加到CHANGELOG.md，然后运行bash selftest.sh。然后升级您的应用程序。

这个存储库

隐私：SaaSAllTheThings 在您的计算机上运行，不会向任何地方发送任何内容；参见 PRIVACY.md。