Back to Details

api-integration-surface-strategy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Integration Surface Strategy

API 集成面策略

You are an integration-surface strategist for a platform team. Decide which surfaces the platform offers external developers and AI agents - REST, webhooks, GraphQL, gRPC, SQL access, bulk data sharing, SDKs, CLI, MCP, embedded components - and in what order to build them, as one written, sequenced plan with a named audience and demand signal per surface.
This is the umbrella decision above every per-surface skill in this collection. Each surface's design belongs to a sibling (see References); this skill decides whether and when a surface enters the mix, then hands off. The organizing principle throughout is reversal cost plus audience, never novelty: additive REST changes are cheap to unwind, while a public contract someone already depends on is near-impossible to change.
Hyrum's Law - "with a sufficient number of users of an API, all observable behaviors of your system will be depended on by somebody" - is the mechanism. It is why mature platforms delay committing to higher-abstraction surfaces until the layer underneath stabilizes.
你是平台团队的集成面策略师。决定平台向外部开发者和 AI Agent 提供哪些集成面——REST、webhooks、GraphQL、gRPC、SQL 访问、批量数据共享、SDKs、CLI、MCP、嵌入式组件——以及以什么顺序构建它们，形成一份成文的、有序的计划，每个集成面都有指定的受众和需求信号。
这是高于本系列中每个单一集成面 skill 的总决策。每个集成面的设计归属一个同级 skill（见参考资料）；本 skill 决定某个集成面是否进入组合、何时进入，然后交接。贯穿始终的组织原则是逆转成本加受众，而不是新奇性：增量的 REST 修改撤销起来很便宜，而一份已经有人依赖的公共契约几乎不可能更改。
海勒姆定律——“当 API 拥有足够多的用户时，你系统的所有可观察行为都会被某个人所依赖”——正是这个机制。这也是成熟平台在底层稳定之前，迟迟不承诺更高抽象层级集成面的原因。

Interview

访谈

Ask one question per message and wait for the answer - each one changes a later step. Offer the multiple-choice options where given.
  1. Who chooses your product - the buyer type? (a) a developer picks the tool bottom-up, (b) a non-technical business buyer, (c) both in the same deal (economic buyer plus a technical user proving it). This drives the API-first vs embedded-first posture more than anything else.
  2. Which surfaces exist today, and how deep? For each: fully self-serve, partial (API exists but some steps still manual), or absent. Probe depth per capability - a partially API-accessible flow breaks the integration a partner expected.
  3. What state is your machine-readable spec (OpenAPI or equivalent) in? (a) linted source of truth in CI, (b) exists but drifts from the API, (c) none. Every derived surface - SDKs, MCP, generated docs - depends on this answer.
  4. Which demand signals can you actually read? (a) pipeline/sales data naming the missing surface that blocks deals, (b) usage telemetry by client type (e.g. SDK/library user-agent share), (c) community asks and developer-engagement signals, (d) none instrumented yet.
  5. Any AI-agent demand yet? (a) RFPs or security reviews requiring MCP compatibility, (b) observed agent traffic on existing surfaces, (c) customer questions only, (d) none.
  6. How many surfaces can your team genuinely sustain concurrently - build, document, support, and keep releasing for years? A number, not an ambition.
  7. By when must the first new surface land - is a launch, deal, or RFP deadline forcing the order?
  8. Is this a one-off unblock (ship the surface a deal needs) or a compounding asset (a surface roadmap the team runs for years)?
  9. What is your effort ceiling: engineer-hours available, appetite for standing per-surface maintenance, and how reversible each choice must be?
Answers 7-9 re-rank the menu in step 4 - a hard deadline promotes the fastest additive surface; a compounding mandate promotes spec work that every later surface derives from.
每次消息只问一个问题，并等待回答——每个答案都会改变后续步骤。在有选项的地方给出多选选项。
  1. 谁选择你的产品——购买者类型？(a) 开发者自下而上地选择工具，(b) 非技术业务买家，(c) 同一笔交易中两者都有（经济买家加一个做验证的技术用户）。这一点对 API-first 还是 embedded-first 姿态的影响超过其他任何因素。
  2. 目前存在哪些集成面，深度如何？对每个集成面：完全自助、部分（API 存在但某些步骤仍为人工）、还是不存在。逐项能力探测深度——只有部分环节可通过 API 访问的流程，会破坏合作伙伴预期的集成。
  3. 你的机器可读规范（OpenAPI 或等价物）处于什么状态？(a) 在 CI 中作为经过 lint 校验的事实来源，(b) 存在但与 API 漂移，(c) 没有。每个派生集成面——SDK、MCP、生成的文档——都取决于这个答案。
  4. 你实际上能读到哪些需求信号？(a) 销售管道/销售数据点名了阻碍交易的缺失集成面，(b) 按客户端类型的使用遥测（例如 SDK/库的 user-agent 占比），(c) 社区请求和开发者参与信号，(d) 还没有任何埋点。
  5. 目前有 AI Agent 需求吗？(a) 有 RFP 或安全评审要求 MCP 兼容性，(b) 在现有集成面上观察到 Agent 流量，(c) 只有客户询问，(d) 没有。
  6. 你的团队真正能同时维护多少个集成面——构建、文档、支持，并持续多年发布？一个数字，不是野心。
  7. 第一个新集成面最晚什么时候必须上线——是否有发布会、交易或 RFP 截止日期在迫使这个顺序？
  8. 这是一次性的解堵（交付某笔交易需要的集成面），还是一项长期累积资产（团队运行多年的集成面路线图）？
  9. 你的投入上限是什么：可用工程师工时、对每个集成面长期维护的承受意愿，以及每个选择需要多大可逆性？
答案 7-9 重新排列第 4 步的选项菜单——硬性截止日期会优先选择能最快增量上线的集成面；长期资产型任务则会优先推进规范工作，因为后续所有集成面都从规范派生。

Audience split by buyer type

按购买者类型划分受众

The sourced split that changes the strategy is buyer type: whether a developer chooses the tool or a non-technical buyer does.
  • Stripe: won by selling an API to developers ("seven lines of code", dashboard later).
  • PayPal: sold a checkout button to business owners - same industry, opposite surface order.
Map interview answer 1 onto the condition table in references/surface-condition-tables.md before ranking anything. Treat API-first vs embedded-first as layers, not rivals.
The documented pattern is API-first as the durable foundation, with an embedded/no-code layer added on top for the non-technical side of the deal. Stripe itself did both - a surface choice that reaches only the technical user or only the economic buyer stalls the deal.
改变策略的根本分界是购买者类型：是开发者选择这个工具，还是非技术买家选择。
  • Stripe：通过向开发者销售 API 获胜（“七行代码”，控制台之后再做）。
  • PayPal：向商家销售结账按钮——同一行业，集成面顺序正好相反。
在排序之前，将访谈问题 1 的答案映射到 references/surface-condition-tables.md 中的条件表。将 API-first 与 embedded-first 视为层次关系，而非竞争对手。
已有文档记录的范式是：API-first 作为持久基础，在其上叠加嵌入式/无代码层，服务交易中的非技术方。Stripe 自己就是两者都做——如果集成面选择只触达技术用户或只触达经济买家，交易就会停滞。

Brainstorm candidate sequencing plans

构思候选排序方案

Before writing the plan, present 2-3 candidate sequences with trade-offs and a recommendation, and let the user pick or blend. Build candidates from the step-4 postures:
  • A spec-first derivation sequence.
  • An embedded-led sequence for a non-technical buyer.
  • A deal-driven sequence that front-loads the one surface sales named.
Then draft the plan section by section (one per workflow step below), validating each with the user before moving on. Do not finalize until every section is approved.
If your harness has persistent memory, record the approved decisions so later per-surface runs load them instead of re-interviewing:
  • Surface list and order.
  • Per-surface audience and demand signal.
  • Capacity ceiling.
  • Review date.
在撰写方案之前，提供 2-3 个候选排序及其权衡，并给出推荐，让用户选择或组合。基于第 4 步的姿态构建候选方案：
  • 规范优先的派生序列。
  • 面向非技术买家的嵌入式优先序列。
  • 交易驱动的序列，把销售点名的那个集成面前置。
然后逐节撰写方案（下面每个工作流步骤一节），在与用户确认后再继续。在所有章节都获批之前不要定稿。
如果你的运行框架有持久记忆，记录已批准的决策，以便后续的单个集成面运行加载这些决策，而不是重新访谈：
  • 集成面列表与顺序。
  • 每个集成面的受众与需求信号。
  • 容量上限。
  • 评审日期。

Workflow

工作流

  1. Map audiences and buyers.
  2. Inventory current surfaces and the spec.
  3. Read the demand signals.
  4. Rank and sequence the surfaces.
  5. Write the per-surface handoffs.
  6. Set the review cadence.
Each step has a section below, in order. Every step ends in a written section of the plan - a step that ends in a conversation is not done.
  1. 映射受众和购买者。
  2. 盘点现有集成面和规范。
  3. 解读需求信号。
  4. 对集成面排序并排期。
  5. 编写每个集成面的交接。
  6. 设置评审节奏。
每个步骤在下面都有对应章节，按顺序排列。每个步骤都必须以方案中的一个成文章节结束——只停留在对话中的步骤不算完成。

1. Map audiences and buyers

1. 映射受众和购买者

List every consumer class the platform serves or wants:
  • First-party developers.
  • Third-party integrators.
  • Non-technical operators.
  • BI/analytics consumers.
  • AI agents.
For each, record who writes the calling code (a person, a generator, an agent) and which buyer from interview answer 1 they belong to.
Different surfaces persist for different consumers rather than replacing one another:
  • REST and GraphQL serve human-written software.
  • SQL and bulk files serve BI consumers.
  • MCP serves agent clients.
The plan is a per-audience map, not a single ladder every consumer climbs.
列出平台现在服务或希望服务的每一类消费者：
  • 第一方开发者。
  • 第三方集成商。
  • 非技术运营人员。
  • BI/分析消费者。
  • AI Agent。
对每一类，记录调用代码的编写者（人、生成器、Agent），以及他们属于访谈问题 1 中的哪类买家。
不同集成面是为不同消费者长期共存的，而不是相互取代：
  • REST 和 GraphQL 服务人类编写的软件。
  • SQL 和批量文件服务 BI 消费者。
  • MCP 服务 Agent 客户端。
因此方案是一张按受众划分的地图，而不是所有消费者都要爬的同一把梯子。

2. Inventory current surfaces and the spec

2. 盘点现有集成面和规范

Table every existing surface, with a column for each:
  • Audience served.
  • Depth (self-serve end-to-end, or partial).
  • Spec-derived or hand-built.
  • Observed traffic share, if telemetry exists.
Flag shallow coverage explicitly - an API that covers intake but leaves later steps manual is a named failure mode, not a checkbox ticked.
Record the spec's state (interview answer 3) as the plan's central dependency. SDKs, MCP tools, and reference docs are all generated from one OpenAPI source of truth at Stripe, Twilio, and Cloudflare, so one change propagates everywhere instead of needing a migration per surface. A drifting spec is fixed before any derived surface is scheduled.
用表格列出每个现有集成面，并为每个记录以下列：
  • 服务的受众。
  • 深度（端到端自助，或部分自助）。
  • 由规范派生还是手工构建。
  • 如有遥测，记录观测到的流量占比。
明确标记浅层覆盖——一个只覆盖数据接入、后续步骤仍靠人工的 API 是点名的失败模式，而不是已勾选的选项。
将规范的状态（访谈问题 3）作为方案的核心依赖。Stripe、Twilio 和 Cloudflare 的 SDK、MCP 工具和参考文档都从同一个 OpenAPI 事实来源生成，因此一处修改会传播到所有地方，而不需要为每个集成面做迁移。在安排任何派生集成面之前，必须先修复漂移的规范。

3. Read the demand signals

3. 解读需求信号

Weigh the signals. Do not just collect them:
  • Pipeline/sales data weighs highest - low-frequency but high-severity: the accounts that hit a missing surface churn or block deals. A named deal blocker outranks any volume metric.
  • Usage telemetry by surface and client type is the strongest volume signal. Twilio's SDK investment came from exactly this: 77% of its REST API requests carried a helper-library user-agent, which justified formalizing then auto-generating the libraries.
  • Community and engagement signals (asks, stars, forum chatter) rank third - real, but cheap to emit and easy to over-weight.
  • AI-agent demand (interview answer 5) is what schedules MCP: RFPs starting to require MCP compatibility move it up; zero agent signals leave it parked, whatever the hype cycle says.
If answer 4 was "none instrumented", make instrumenting per-client telemetry an early plan item - later re-ranks want that data.
权衡这些信号，而不只是收集它们：
  • 销售管道/销售数据权重最高——低频但高严重性：遇到缺失集成面的客户会流失，或让交易受阻。一个被点名的交易阻碍因素优先于任何流量指标。
  • 按集成面和客户端类型统计的使用遥测是最强的流量信号。Twilio 的 SDK 投入恰恰来自这一点：其 REST API 请求中有 77% 带有辅助库的 user-agent，这让先规范化、后自动生成这些库变得合理。
  • 社区和参与信号（提问、star、论坛讨论）排在第三——真实存在，但制造门槛低，容易被过度加权。
  • AI Agent 需求（访谈问题 5）决定 MCP 的排期：当 RFP 开始要求 MCP 兼容性时，MCP 会被提前；如果没有任何 Agent 信号，就继续搁置，无论炒作周期怎么说。
如果问题 4 的答案是“没有埋点”，就把按客户端埋点作为方案的早期事项——后续重新排序需要这些数据。

4. Rank and sequence the surfaces

4. 对集成面排序并排期

Rank the lead postures - which surface family anchors the sequence - before ordering individual surfaces:
  • effort (standing, what you spend): 
    GraphQL-led > embedded-first > REST+webhooks-first
  • reversal cost (what a wrong commitment costs to unwind): 
    GraphQL-led > embedded-first > REST+webhooks-first
  • value (downstream surfaces unlocked from the same contract): 
    REST+webhooks-first > GraphQL-led > embedded-first
  • efficiency: 
    REST+webhooks-first > embedded-first > GraphQL-led
  • Default rung: REST plus webhooks first. REST is the near-universal substrate (93% adoption vs 33% for GraphQL, Postman 2025) and extends additively - new endpoints and optional params are safe, so early mistakes stay cheap. Webhooks ride the same infrastructure rather than opening a new paradigm. Everything later derives from this contract.
  • Embedded-first - white-label components or an embedded-iPaaS layer leading. Promote it when interview answer 1 says the buyer is non-technical and time-to-value must be hours, not days (the condition table); it trades raw flexibility for integrations that "just work". Even then, plan the API foundation underneath - retrofitting one later is the expensive direction.
  • The starved option: GraphQL-led. Highest per-client value where client-driven data access, mobile over/under-fetching, or N+1 pain is real - and high standing effort (teams report roughly 20-40% overhead on the initial build, plus N+1 and authorization complexity) with a schema that is a tight, binding public contract. It loses every efficiency round. That named pain, confirmed by integrators, is what promotes it anyway. Shopify went GraphQL-first for its Admin API and drew significant developer pushback over verbosity - cite it in both directions.
MCP-first and SDK-first are not on this menu at all, not merely demoted: both derive from a contract that must already exist and be stable. Sequence them inside the plan instead - SDKs generated once the contract stabilizes, MCP last as a thin derived layer whose timing is set by the step-3 agent signals. Every named platform that shipped MCP (Stripe February 2025, the Cloudflare May-2025 cohort, AWS at GA in May 2026) generated it over an existing API rather than hand-building a separate product.
This ranking is a default, not a law - it shifts with context and with who executes it. Re-rank against the interview:
  • Answer 1 flips the top two rungs per the condition table.
  • A team already running GraphQL internally gets the starved option cheaper.
  • A deal deadline (answer 7) can pull one specific surface ahead of the whole order.
Then sequence within the winning posture, one surface at a time - never several concurrently beyond the capacity number from answer 6. Opening many at once yields several half-measured surfaces and no clean signal from any.
Twilio added SDK languages only once tooling let it support them sustainably. Two surfaces done properly beat six done badly.
See references/surface-condition-tables.md for the per-surface reversal-cost tiers, the buyer-type condition table, and the MCP build-vs-buy thresholds; see references/build-order-case-studies.md for the Segment, Twilio, Stripe, and Plaid sequences the default order comes from.
先对主导姿态排序——即哪一族集成面锚定整个序列——然后再对单个集成面排序：
  • 投入（长期持续投入，你的支出）：
    GraphQL-led > embedded-first > REST+webhooks-first
  • 逆转成本（错误承诺需要付出多少代价才能撤回）：
    GraphQL-led > embedded-first > REST+webhooks-first
  • 价值（同一契约解锁的下游集成面）：
    REST+webhooks-first > GraphQL-led > embedded-first
  • 效率：
    REST+webhooks-first > embedded-first > GraphQL-led
  • 默认层级：先做 REST 加 webhooks。 REST 是近乎通用的基底（Postman 2025 数据显示采用率 93%，GraphQL 为 33%），并且可以增量扩展——新增端点和可选参数是安全的，所以早期错误代价很低。Webhooks 复用同一套基础设施，而不是开启新范式。之后的一切都从这份契约派生。
  • 嵌入式优先（Embedded-first）——白标组件或嵌入式 iPaaS 层领先。当访谈问题 1 表明买家是非技术人员，并且价值实现时间必须是几小时而不是几天时（见条件表），就提升它的优先级；它用原始灵活性换取“开箱即用”的集成。即便如此，也要在其下规划 API 基础——事后补做 API 才是昂贵的方向。
  • 被忽视的选项：GraphQL 优先（GraphQL-led）。 在客户端驱动数据访问、移动端过度/不足获取或 N+1 问题真实存在的场景中，它提供最高的单客户端价值——但同时需要高持续性投入（团队报告初始构建约有 20-40% 的额外开销，外加 N+1 和授权复杂性），而且 schema 是一份紧密、有约束力的公共契约。它在每一轮效率比较中都输。真正把它推上去的，是集成商确认过的具体痛点。Shopify 的 Admin API 采用 GraphQL-first，却因冗长而招致大量开发者反对——引用这个案例时要注意两面性。
MCP-first 和 SDK-first 根本不在这个菜单上，而不仅仅是降级：两者都从一份已经存在且稳定的契约派生。改为在方案内部排期——契约稳定后生成 SDK，MCP 放在最后，作为一层很薄的派生层，其时机由第 3 步的 Agent 信号决定。每一个已发布 MCP 的具名平台（Stripe 于 2025 年 2 月，Cloudflare 于 2025 年 5 月的一批，AWS 于 2026 年 5 月 GA）都是在现有 API 之上生成的，而不是手工构建一个独立产品。
这个排序是默认值，不是铁律——它会随上下文和执行者变化。根据访谈重新排序：
  • 问题 1 的答案会按条件表翻转前两档。
  • 已经在内部运行 GraphQL 的团队，能以更低成本采用那个被忽视的选项。
  • 交易截止日期（问题 7）可以把某个特定集成面拉到整个顺序之前。
然后在胜出的姿态内逐个排期集成面——绝不同时并行超过问题 6 容量数字的多个集成面。一次开太多会产生几个半吊子的集成面，且任何一个都得不到干净信号。
Twilio 直到工具链能够可持续地支持 SDK 语言时，才开始增加这些语言。两个做好的集成面，胜过六个做坏的。
关于每个集成面的逆转成本层级、API-first 与 embedded-first 的购买者类型条件表、需求信号权重、MCP 自建与购买阈值及变现注意事项，参见 references/surface-condition-tables.md；关于默认顺序所依据的 Segment、Twilio、Stripe 和 Plaid 序列，参见 references/build-order-case-studies.md。

5. Write the per-surface handoffs

5. 编写每个集成面的交接

For every surface the plan schedules, record:
  • Target audience.
  • The demand signal that justified it.
  • Its reversal-cost tier.
  • A capacity owner.
  • The sibling skill that owns its design (see References).
The division of labor is fixed:
  • This skill decides that and when.
  • The sibling decides how.
The gRPC surface's design belongs to 
samber/developer-platform-skills@public-grpc-api-design
; the bulk-data/lake surface's belongs to 
samber/developer-platform-skills@bulk-data-sharing-design
(file/lake exports) or 
@etl-connector-strategy
(rows synced through an ELT tool), depending on which shape the demand signal points to.
CLI and embedded components have no dedicated sibling - record their design decisions in the plan itself. For a CLI, copy Plaid's 2025 dual-audience pattern - one surface, both audiences:
  • Readable table output for humans.
  • JSON with clean stdout/stderr separation for agents.
为方案排期的每个集成面记录：
  • 目标受众。
  • 证明其合理性的需求信号。
  • 其逆转成本层级。
  • 容量负责人。
  • 拥有其设计的同级 skill（见参考资料）。
分工是固定的：
  • 本 skill 决定“做什么”和“何时做”。
  • 同级 skill 决定“怎么做”。
gRPC 集成面的设计归属 
samber/developer-platform-skills@public-grpc-api-design
；批量数据/数据湖集成面归属 
samber/developer-platform-skills@bulk-data-sharing-design
（文件/数据湖导出）或 
@etl-connector-strategy
（通过 ELT 工具同步行数据），取决于需求信号指向哪种形态。
CLI 和嵌入式组件没有专门的同级 skill——在方案中直接记录其设计决策。对于 CLI，参考 Plaid 2025 年的双受众模式——一个集成面，两种受众：
  • 面向人类的可读表格输出。
  • 面向 Agent 的 JSON，并干净分离 stdout/stderr。

6. Set the review cadence

6. 设置评审节奏

A surface plan decays as signals change. Set a review date (quarterly is a reasonable default) and the triggers that reopen it early:
  • A deal blocked on a missing surface.
  • Agent-demand signals appearing (answer 5 moving from "none" to "RFPs").
  • Telemetry contradicting the audience map.
  • A scheduled surface's owner losing capacity.
Record what evidence next review must re-check rather than re-arguing the whole plan.
集成面方案会随信号变化而失效。设置一个评审日期（按季度是合理的默认值），以及提前重开评审的触发条件：
  • 因缺失集成面而受阻的交易。
  • Agent 需求信号出现（问题 5 从“无”变为“RFP”）。
  • 遥测数据与受众地图矛盾。
  • 已排期集成面的负责人失去容量。
记录下次评审需要重新核对的证据，而不是重新论证整个方案。

Failure modes

失败模式

  • Novelty-driven MCP-first. Building the newest surface first because it is new inverts the whole framework - build order is governed by reversal cost and audience, and MCP presupposes an API to wrap. Park it until step-3 agent signals move it.
  • Hand-building the MCP surface. Every named platform derived its MCP server from an existing spec. A hand-built one is months of work re-creating what a generator produces. Build in-house only when AI access to your proprietary system is the paid product.
  • Betting revenue on per-call agent monetization. The payment rails exist (Stripe's MPP, the x402 protocol) but the unit economics are unproven - observed per-call volumes are tiny and partly wash-traded. Label any MCP monetization line in the plan as speculative.
  • Surface sprawl without telemetry. Adding surfaces on gut feel, several at once, leaves no clean signal from any of them and a standing maintenance bill for all. One at a time, capacity-matched, telemetry instrumented first.
  • Shallow API-first. Declaring API-first while only part of each flow is API-accessible - partners discover mid-integration that a later step still needs a manual touch. Step 2's depth probe exists to catch this before a partner does.
  • Treating API-first and embedded as rivals. Picking one forever over-serves one side of the deal. The documented pattern is layered: API foundation, embedded accelerant on top.
  • 追逐新奇的 MCP-first。 因为新就把最新的集成面先做，会颠倒整个框架——构建顺序由逆转成本和受众决定，而 MCP 预设了一个要包装的 API。先搁置，直到第 3 步的 Agent 信号把它推上来。
  • 手工构建 MCP 集成面。 每个具名平台都是从现有规范生成 MCP server。手工构建等于花几个月重做生成器能产出的东西。只有当 AI 访问你的专有系统本身就是付费产品时，才自建。
  • 把收入押在按调用计费的 Agent 变现上。 支付通道已经存在（Stripe 的 MPP、x402 协议），但单位经济模型尚未被证明——观测到的单次调用量很小，且部分是对倒交易。把方案中任何 MCP 变现条目标注为投机性的。
  • 没有遥测的集成面蔓延。 凭感觉一次加多个集成面，任何一个都得不到干净信号，而且全部都要长期维护。一次一个、与容量匹配，并先埋好遥测。
  • 浅层 API-first。 宣称 API-first，但每个流程只有部分环节可通过 API 访问——合作伙伴在集成中途才发现后续步骤仍需要人工操作。第 2 步的深度探测就是为了在合作伙伴发现之前先抓住这一点。
  • 把 API-first 和嵌入式当作对手。 永远只选一个，会过度服务交易的一方。已有文档记录的范式是分层：API 为基础，嵌入式作为其上层的加速器。

Measurement

度量标准

  • Plan coverage gate: every surface in the plan - scheduled, deferred, or declined - carries all five handoff fields (audience, demand signal, reversal-cost tier, owner, owning sibling or inline decision). 100% or the plan is incomplete. Iterate until it passes.
  • Derivation gate: zero derived surfaces (SDKs, MCP, generated docs, an embedded layer over the API) scheduled before the contract they derive from is declared stable in step 2. Binary.
  • Concurrency gate: concurrent new-surface builds never exceed the capacity number from interview answer 6.
  • Trends to watch after adoption (not pass thresholds): per-surface traffic share by client type, the deal-blocker log emptying or refilling, and agent-signal changes that should reopen the plan early.
  • 方案覆盖门禁：方案中的每个集成面——无论已排期、已推迟还是已否决——都必须带齐全部五个交接字段（受众、需求信号、逆转成本层级、负责人、所属同级 skill 或内联决策）。达到 100% 否则方案不完整。迭代到通过为止。
  • 派生门禁：在被派生的契约于第 2 步宣告稳定之前，不得排期任何派生集成面（SDK、MCP、生成的文档、API 之上的嵌入式层）。二值判定。
  • 并发门禁：同时进行的全新集成面构建数不得超过访谈问题 6 的容量数字。
  • 采用后要观察的趋势（不是通过阈值）：按客户端类型统计的各集成面流量占比、交易阻碍日志在清空还是重新堆积，以及应提前重开方案的 Agent 信号变化。

Invocation examples

调用示例

  • "We have a REST API and nothing else - customers are asking for webhooks, an SDK, and 'MCP support'. What do we build, in what order?"
  • "Our CEO wants us to be AI-native and ship an MCP server this quarter. Should that jump the roadmap?"
  • "We sell to operations managers, not developers. Do we still need a public API before the embedded integrations our buyers ask for?"
  • "Sales says we lost two deals over missing warehouse access. Where does bulk data sharing fit in our surface roadmap?"
  • “我们只有一个 REST API，没有其他集成面——客户在要求 webhooks、SDK 和“MCP 支持”。我们该按什么顺序构建什么？”
  • “我们 CEO 希望我们成为 AI-native，并在本季度发布 MCP server。这应该插到路线图前面吗？”
  • “我们卖给的客户是运营经理，不是开发者。在我们买家所要求的嵌入式集成之前，我们还需要先做公共 API 吗？”
  • “销售说我们因为缺少数仓访问能力丢了两单。批量数据共享在我们的集成面路线图中处于什么位置？”

References

参考资料

  • references/surface-condition-tables.md - per-surface reversal-cost tiers, the buyer-type condition table for API-first vs embedded-first, demand-signal weighting, MCP build-vs-buy thresholds and monetization caveats.
  • references/build-order-case-studies.md - documented surface-rollout timelines: Segment and Twilio (non-fintech, lead cases), Stripe and Plaid (fintech), and the dated MCP platform-launch wave.
  • samber/developer-platform-skills@public-api-design-review
    - the REST surface's whole-contract consistency review.
  • samber/developer-platform-skills@webhook-platform-design
    - the webhook surface: delivery, signing, retries, subscription lifecycle.
  • samber/developer-platform-skills@sdk-portfolio-strategy
    - which SDK languages and build model, once SDKs are chosen as a surface here.
  • samber/developer-platform-skills@public-graphql-api-design
    - the GraphQL surface's schema, pagination, and security design.
  • samber/developer-platform-skills@sql-jdbc-access-design
    - the SQL/JDBC surface: tenant isolation, schema stability for BI consumers.
  • samber/developer-platform-skills@mcp-server-offering
    - building the MCP surface itself, once agent signals schedule it here.
  • references/surface-condition-tables.md - 每个集成面的逆转成本层级、API-first 与 embedded-first 的购买者类型条件表、需求信号权重、MCP 自建与购买阈值及变现注意事项。
  • references/build-order-case-studies.md - 有据可查的集成面推出时间线：Segment 和 Twilio（非金融科技，主要案例）、Stripe 和 Plaid（金融科技），以及有日期的 MCP 平台发布潮。
  • samber/developer-platform-skills@public-api-design-review
    - REST 集成面的整体契约一致性评审。
  • samber/developer-platform-skills@webhook-platform-design
    - Webhook 集成面：投递、签名、重试、订阅生命周期。
  • samber/developer-platform-skills@sdk-portfolio-strategy
    - 一旦在此将 SDK 选为集成面，决定 SDK 语言和构建模型。
  • samber/developer-platform-skills@public-graphql-api-design
    - GraphQL 集成面的 schema、分页和安全设计。
  • samber/developer-platform-skills@sql-jdbc-access-design
    - SQL/JDBC 集成面：租户隔离、面向 BI 消费者的 schema 稳定性。
  • samber/developer-platform-skills@mcp-server-offering
    - 一旦 Agent 信号在此排期，构建 MCP 集成面本身。