SEC EDGAR for Developers: The Free Fundamentals API Hiding in Plain Sight

You finished the comparison shopping between Polygon and Alpha
Vantage, maybe even signed up for a free tier of each. Now you
want to pull fundamentals — revenue, earnings, free cash flow —
for your screener.

Don’t reach for the paid tier just yet. The SEC publishes every
filing from every public US company through a free, well-
structured JSON API at data.sec.gov. It’s unrated, public, and
the data is straight from the source.

What EDGAR actually exposes

Three endpoints do most of the work:

  • /submissions/CIK{cik}.json — every filing a company has
    made, with dates, accession numbers, and direct links to the
    documents.
  • /api/xbrl/companyfacts/CIK{cik}.json — every reported XBRL
    fact for that company, across all filings, indexed by concept
    (Revenues, NetIncomeLoss, Assets, etc.) and unit.
  • /api/xbrl/companyconcept/CIK{cik}/us-gaap/{concept}.json —
    just one concept across all reported periods.

The companyfacts endpoint is the workhorse. One JSON request
and you have every quarterly and annual fact the company has
filed with the SEC since they switched to XBRL in 2009.

The annoying part: CIK lookup

EDGAR keys companies by CIK (Central Index Key), not ticker.
You’ll need to maintain or fetch a ticker → CIK map. The SEC
publishes one:

curl -A 'your-name [email protected]' 
  https://www.sec.gov/files/company_tickers.json

The User-Agent header is required — EDGAR rate-limits anonymous
requests and asks for an identifying string. They throttle at 10
requests/second across all clients; respect it.

A minimal example

Here’s the smallest useful thing — pulling the last 4 quarterly
revenues for Apple (CIK 0000320193):

import requests

headers = {'User-Agent': 'side-project [email protected]'}
url = (
    'https://data.sec.gov/api/xbrl/companyconcept/'
    'CIK0000320193/us-gaap/Revenues.json'
)

r = requests.get(url, headers=headers)
data = r.json()

# units may include USD and USD/shares; pick USD
usd = data['units']['USD']
# 10-Q quarterly filings only
quarterly = [f for f in usd if f.get('form') == '10-Q']
quarterly.sort(key=lambda f: f['end'], reverse=True)
for f in quarterly[:4]:
    print(f"{f['end']}: ${f['val']:,}")

That’s it. Free, structured, official.

When EDGAR wins

  • No rate-limit drama for any volume a side project can
    generate.
  • Authoritative — straight from filings. No vendor between
    you and the company’s own numbers.
  • Historical depth since 2009 for most large filers, earlier
    in some cases.

Where EDGAR struggles

  • Concept fragmentation. Companies don’t all use the same
    XBRL concept for the same thing. Apple uses Revenues; some
    others have used SalesRevenueNet or company-specific
    extensions. Real cleanup work.
  • Restated filings. When a company restates an earlier
    quarter, EDGAR contains both the original and the restated
    values. Your code has to decide which one is “the truth” for
    backtest purposes.
  • Calendar mismatch. Companies report on different fiscal
    calendars. You can’t naively compare one issuer’s Q1 ending in
    December to another’s Q1 ending in September.
  • No price data. EDGAR is filings, not market data. You
    still need Polygon, Alpha Vantage, or similar for OHLC.

A reasonable production setup

For a magic-formula-style screener:

  1. Maintain a local cik_map table (refresh weekly from SEC’s
    company_tickers.json).
  2. For each ticker in your universe, fetch companyfacts once
    and cache. Refresh on a quarterly cadence — fundamentals
    don’t change daily.
  3. Normalize concepts to your own internal names (revenues,
    net_income, total_assets, etc.) with a hand-curated
    mapping that tolerates fragmentation.
  4. Get prices from your paid or free price-data API.
  5. Run your ranking once a week — it’s cheaper than the daily
    refresh cadence most tutorials suggest.

The hardest part of building a fundamentals pipeline is not the
API — it’s the concept normalization. Budget more time for
“decide what counts as revenue across 500 issuers” than for
“wire up the HTTP request.” Get it wrong and your screener
silently ranks the inconsistent reporters.

Closing note

The fundamentals data that paid APIs charge for is largely a
cleaned-up, normalized version of what EDGAR already gives you
for free. If your project is willing to do the cleanup, EDGAR is
the better foundation. If you’d rather pay a vendor to handle the
normalization, that’s also a reasonable choice. Either way,
knowing the raw source exists changes how you think about the
cost of building.

Originally published at pickuma.com. Subscribe to the RSS or follow @pickuma.bsky.social for new reviews.

现代化 UI 架构:Drawable 层规范与工程实践

本文是 UI 架构系列的第二篇,建议先阅读 第一篇:三层颜色体系与系统化设计方案 了解核心设计理念。

前言

在上一篇文章中,我们建立了一套完整的颜色体系。但颜色只是 UI 的基础,真正让 UI 活起来的是形态和交互。

一个按钮不仅需要颜色,还需要:

  • 圆角、描边、阴影
  • 按下、禁用、选中的状态变化
  • 渐变、透明等视觉效果

这些都需要通过 Drawable 来实现。

贯穿 UI 架构层的一条铁律:颜色、Drawable、Style 等所有资源定义,都不要和业务挂钩;命名表达的是 UI 职能,职能 ≠ 业务。一旦用「登录页按钮」「订单失败红框」这类业务语义去命名或拆分资源,就等于把形态和颜色锁死在某个页面——可复用性会被立刻破坏。Drawable 层只描述形态、色系、交互状态与档位,业务含义由使用它的页面自己承担。

跨平台:Android 的 Drawable/selector 对应 iOS 的 Asset Catalog 状态图、Web 的 design-token + CSS 状态类;命名与分层思想一致。

本文要点:

  1. 为什么需要 Drawable 层规范
  2. Drawable 层的三层架构设计
  3. 统一的命名规范
  4. 形态层和组件层的设计要点

一、为什么需要 Drawable 层规范?

1.1 反例:混乱的 Drawable 管理

在我接触过的项目中,经常会看到这样的 Drawable 定义:

<!-- btn_primary.xml -->
<shape>
    <solid android:color="#FF4B00" />
    <corners android:radius="24dp" />
</shape>

<!-- btn_primary_pressed.xml -->
<shape>
    <solid android:color="#CC3D00" />
    <corners android:radius="24dp" />
</shape>

<!-- btn_disabled.xml -->
<shape>
    <solid android:color="#CCCCCC" />
    <corners android:radius="24dp" />
</shape>

1.2 问题分析

问题类型 具体表现 影响
重复定义 每个状态都要单独定义一个文件 维护成本高
颜色硬编码 直接写色值,无法跟随主题切换 主题适配困难
命名混乱 btn_primary、button_normal 等命名不统一 新人难以选择
难以维护 改一个圆角需要修改所有文件 修改成本高

1.3 根本原因

这些问题的本质在于:形态定义与颜色、状态过度耦合。当一个 Drawable 文件同时承载了形状、颜色和状态逻辑时,任何改动都会变得非常困难。

二、Drawable 层的三层架构

借鉴颜色体系的设计思路,我们同样采用三层架构来管理 Drawable:

2.1 核心原则

层级 职责 特点
组件层 组合状态和形态 通过 selector 引用 bg_*,实现状态切换
形态层 定义圆角、描边、填充结构 颜色只引用 func_*,禁止硬编码色值
颜色层 提供颜色 token 设计师维护的功能色,支持主题切换

与业务解耦:三层都只表达「UI 语言」,不表达「业务故事」。sel_orange_interact_capsule_emphasis_default 可以在下单主按钮、会员开通按钮、活动页主按钮上复用;若做成 sel_order_submit_primary,换页面就要复制一套 Drawable,主题与形态也无法在全 App 统一维护。

三、命名规范:让每个文件都有明确的含义

3.1 命名公式

{类型}_{色系}_{用途}_{状态}_{档位}

3.2 组成说明

组成部分 说明 允许值
类型 Drawable 类别 bg(背景)、sel(选择器)、ic(图标)
色系 颜色分类 gray、orange、red、blue、green、black、white
用途 使用场景 surface、fill、stroke、field、interact、gradient
状态 交互状态 idle、alert、hint、emphasis、neutral、default
档位 优先级 数字 1(主要)、2(次要)、3(第三)

3.3 命名示例

bg_orange_fill_interact_1    // 橙色交互填充背景,主档位
bg_gray_surface_card_1       // 灰色卡片表面背景
sel_orange_interact_outline_emphasis_default  // 橙色描边交互选择器
bg_black_fill_scrim_1        // 黑色遮罩填充

3.4 反例:业务绑定如何毁掉复用

❌ 错误:文件名承载业务,无法跨场景复用
bg_login_page_primary_btn.xml
bg_order_detail_pay_btn.xml
sel_profile_avatar_upload_error.xml

三个文件往往只是圆角、色值、状态略有相似,却无法合并维护。正确做法是共用 sel_orange_interact_capsule_emphasis_default 等职能 + 形态命名,由不同页面的布局或 Style 决定用在哪里。

四、形态层设计:结构 + 功能色引用

4.1 基础形状类型

形状 用途 示例
fill 实心填充 按钮背景、卡片背景
stroke 描边空心 输入框边框、幽灵按钮
flat 扁平透明 文字按钮、点击区域
gradient 渐变效果 渐变背景、光晕效果
surface 表面效果 卡片、浮层、阴影

4.2 形状定义规范

<!-- bg_orange_fill_interact_1.xml -->
<shape xmlns:android="http://schemas.android.com/apk/res/android"
    android:shape="rectangle">
    <solid android:color="@color/func_orange_bg_1" />
    <corners android:radius="@dimen/draw_corner_capsule" />
</shape>

<!-- bg_orange_stroke_interact_1.xml -->
<shape xmlns:android="http://schemas.android.com/apk/res/android"
    android:shape="rectangle">
    <solid android:color="@color/func_clear_1" />  <!-- 透明填充 -->
    <stroke 
        android:width="@dimen/draw_stroke_reg" 
        android:color="@color/func_orange_border_1" />
    <corners android:radius="@dimen/draw_corner_capsule" />
</shape>

关键设计点:

  • 使用 @dimen 引用尺寸(由设计师在 dimens 中定义),避免硬编码
  • 使用 @color/func_* 引用功能色,支持主题切换;禁止在 drawable 中写 #RRGGBB 或直接引用 t_*、基础色
  • 同一套圆角/描边结构可搭配不同色系的功能色,由设计师在 token 层切换映射

五、状态色设计:状态逻辑放在 Drawable 层

在设计这套体系时,我们曾讨论过是否需要添加「禁用态」「选中态」「按下态」等状态相关的颜色到颜色层。

结论:状态色应该放在 drawable 层,而不是颜色层。

状态类型 建议位置 原因
禁用态 drawable层 通过selector组合实现
选中态 drawable层 通过selector组合实现
按下态 drawable层 通过selector组合实现

5.1 为什么不在颜色层定义状态色?

  1. 职责分离:颜色层负责提供「原料」,drawable层负责组合「成品」
  2. 灵活性:同一个颜色可以在不同状态下有不同表现
  3. 可复用性:一套颜色可以组合出多种状态效果

5.2 状态效果的正确实现方式

<!-- drawable/sel_orange_interact_capsule_emphasis_default.xml -->
<selector xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- 禁用态 -->
    <item android:state_enabled="false">
        <shape>
            <solid android:color="@color/func_black_bg_2" />  <!-- 禁用态用灰色背景 -->
            <corners android:radius="24dp" />
        </shape>
    </item>
    <!-- 按下态 -->
    <item android:state_pressed="true">
        <shape>
            <solid android:color="@color/func_orange_bg_2" />  <!-- 按下态用浅色 -->
            <corners android:radius="24dp" />
        </shape>
    </item>
    <!-- 常态 -->
    <item>
        <shape>
            <solid android:color="@color/func_orange_bg_1" />  <!-- 常态用主色 -->
            <corners android:radius="24dp" />
        </shape>
    </item>
</selector>

六、组件层设计:状态组合

6.1 Selector 的规范写法

<!-- sel_orange_interact_capsule_emphasis_default.xml -->
<selector xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- 禁用态 -->
    <item 
        android:drawable="@drawable/bg_gray_fill_interact_2" 
        android:state_enabled="false" />
    <!-- 按下态 -->
    <item 
        android:drawable="@drawable/bg_orange_fill_interact_2" 
        android:state_pressed="true" />
    <!-- 常态 -->
    <item android:drawable="@drawable/bg_orange_fill_interact_1" />
</selector>

6.2 状态优先级

Selector 中状态判断优先级(高 → 低):禁用态 > 选中态 > 按下态 > 焦点态 > 常态

6.3 输入框状态示例

<!-- sel_gray_field_rect_idle_default.xml -->
<selector xmlns:android="http://schemas.android.com/apk/res/android">
    <item 
        android:drawable="@drawable/bg_gray_field_rect_2" 
        android:state_enabled="false" />
    <item 
        android:drawable="@drawable/bg_blue_field_rect_1" 
        android:state_focused="true" />
    <item android:drawable="@drawable/bg_gray_field_rect_1" />
</selector>

七、常用组件的 Drawable 实现

7.1 按钮组件

按钮类型 Drawable 配置
主按钮 sel_orange_interact_capsule_emphasis_default
次按钮 sel_gray_interact_capsule_neutral_default
文字按钮 sel_gray_interact_flat_neutral_default
幽灵按钮 sel_orange_interact_outline_emphasis_default

7.2 输入框组件

状态 Drawable 配置
常态 sel_gray_field_rect_idle_default
警告态 sel_yellow_field_rect_hint_static
错误态 sel_red_field_rect_alert_static

7.3 卡片组件

卡片类型 Drawable 配置
普通卡片 bg_gray_surface_card_1
浮层卡片 bg_gray_surface_float_1
面板卡片 bg_gray_surface_panel_1

八、尺寸管理:统一的 Dimen 规范

8.1 圆角尺寸

<!-- dimens_drawable.xml -->
<dimen name="draw_corner_none">0dp</dimen>
<dimen name="draw_corner_sm">4dp</dimen>
<dimen name="draw_corner_reg">8dp</dimen>
<dimen name="draw_corner_lg">12dp</dimen>
<dimen name="draw_corner_capsule">999dp</dimen>  <!-- 胶囊形 -->

8.2 描边尺寸

<dimen name="draw_stroke_thin">0.5dp</dimen>
<dimen name="draw_stroke_reg">1dp</dimen>
<dimen name="draw_stroke_thick">2dp</dimen>

8.3 阴影尺寸

<dimen name="draw_shadow_elevation_1">2dp</dimen>
<dimen name="draw_shadow_elevation_2">4dp</dimen>
<dimen name="draw_shadow_elevation_3">8dp</dimen>

九、与颜色体系的集成

9.1 颜色引用规范

<!-- ✅ 正确:引用功能色层 -->
<solid android:color="@color/func_orange_bg_1" />
<stroke android:color="@color/func_orange_border_1" />

<!-- ❌ 错误:直接引用主题色或基础色 -->
<solid android:color="@color/t_orange_4" />  <!-- 不推荐 -->
<solid android:color="@color/orange_4" />    <!-- 禁止 -->

9.2 夜间模式自动适配

得益于三层颜色架构,Drawable 层无需任何修改即可支持夜间模式:

日间模式:
func_orange_bg_1 → t_orange_4 → orange_4 (#FF4B00)

夜间模式:
func_orange_bg_1 → t_orange_4 → orange_3b (#FF8833)

十、与 View 的集成方式

10.1 通过 Style 引用

<!-- styles_button.xml -->
<style name="Btn.Orange.Capsule.Emphasis" parent="BaseButton">
    <item name="android:background">@drawable/sel_orange_interact_capsule_emphasis_default</item>
    <item name="android:textColor">@color/func_white_text_1</item>
</style>

10.2 在布局中直接使用

<Button
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:background="@drawable/sel_orange_interact_capsule_emphasis_default"
    android:text="主操作" />

十一、完整架构总结

十二、总结

Drawable 层是连接颜色和 UI 组件的桥梁,它的设计直接影响到:

  • UI 的一致性和美观度
  • 代码的可维护性
  • 主题切换的灵活性

通过遵循以下原则,你可以构建一套优秀的 Drawable 体系:

  1. 与业务解耦:Drawable 只表达形态与交互语义,绝不使用页面名、流程名、业务事件名
  2. 分离关注点:形态结构与填色引用分离,状态组合与组件分离
  3. 统一命名规范:{类型}_{色系}_{用途}_{状态}_{档位}
  4. 复用优先:避免重复定义,提高资源利用率
  5. 与颜色体系集成:只引用设计师定义的 func_*,支持主题切换

参考代码:

💡 如果你觉得这篇文章对你有帮助,欢迎点赞、收藏、转发。关注我,获取更多 Android 架构设计干货。

系列文章:

When AI Meets Reality: Why “Hello World” Isn’t Enough for LLM Systems

Most AI tutorials stop at “Hello World.” You wire up a model, send a prompt, get a response, and feel like you’ve built something. But the moment you try to ship that into production, the ground shifts beneath your feet.

I learned this the hard way. After years of building fraud detection and pricing platforms, I’ve seen what happens when AI systems collide with real‑world state changes, concurrency, and regulatory scrutiny. Spoiler: it’s not pretty.

The Mirage of Staging

Staging environments are polite liars. They don’t tell you how load will spike, how data will mutate mid‑transaction, or how context drift will break your assumptions. In production, milliseconds matter. A competitor reprices, a stock threshold flips, and suddenly your “correct” model output is wrong for the world it lands in.

Lesson: Treat context as a snapshot contract. Immutable, versioned, and validated before any downstream commit. If the snapshot is stale, abort. Re‑orchestrate. Don’t trust staging to teach you this — production will.

Failure Modes Define Architecture

Fraud vs. pricing taught me the most important architectural lesson: not all signals are equal.

  • Fraud: high‑frequency, asymmetric cost of false negatives → fail‑closed defaults.
  • Pricing: lower frequency, asymmetric cost of false positives → fail‑open defaults.

Copy‑pasting validation strategies across domains is malpractice. Map your failure modes first. Let the asymmetry drive your fallback design.

Prompts Are Contracts Too

We version APIs. We version schemas. We rarely version prompts. That’s how a “minor tweak” silently broke a fraud classifier pipeline for six hours. The fix was simple: git‑tracked prompts, version IDs in every call, and audit logs that tie outputs back to prompt versions.

Audit trails aren’t just for compliance. They’re the only way to answer the inevitable question: did the model drift, did the prompt drift, or did the world drift?

The Trust Layer Is Load‑Bearing

Most teams skip it. Schema enforcement, confidence routing, semantic drift detection — all postponed until the first incident. By then, retrofitting costs months. Build it upfront. It’s not a safety net; it’s part of the foundation.

Build Boring AI

The model is not the system. The system earns the right to touch production state through contracts, validation, bounded context, and auditability. Every shortcut you take here will come back as a pager at 2am.

If you want to sleep at night, build boring AI systems. Your future self will thank you.

现代化 UI 架构:三层颜色体系与系统化设计方案

本文是 UI 架构系列 的第一篇,将深入探讨颜色层的设计。后续文章将依次介绍:

注:本文以 Android 为例进行说明,但核心思想完全适用于 iOS、React、H5、小程序等任何平台。

前言

在多年的跨平台 App 开发实践中,我发现 UI 资源管理是困扰许多团队的共性问题:

  • 颜色定义混乱,同一个色值重复定义几十次
  • 组件形态与颜色过度耦合,难以复用
  • 样式属性重复书写,维护成本极高
  • 主题切换困难,夜间模式适配工作量巨大
  • 新同事需要花费大量时间理解混乱的颜色命名

如果你也被这些问题困扰,这个系列或许值得一读——主要面向设计总监、设计师、研发总监与前端工程师。

本文要点:

  1. 三层颜色架构的设计理念和核心原则
  2. 每一层的具体设计规范和代码实现
  3. 如何实现日间/夜间模式的无缝切换
  4. 架构的适用场景和扩展方向

架构全景

本系列介绍的是一套完整的 UI 架构体系,其中三层颜色架构是核心基础:

箭头表示引用/依赖方向:应用层引用 func_;func_* 引用 t_;t_ 引用基础色。定义权在设计侧,自下而上配置。*

颜色层依赖关系:func_* → t_* → 基础色(严格单向依赖)

本文聚焦于三层颜色架构的完整设计,后续文章将介绍上层应用层如何基于颜色层构建。

一、传统颜色管理的核心痛点

1.1 真实项目中的反例

在我接触过的多个项目中,经常会看到类似这样的颜色定义:

<!-- 从真实项目中截取的颜色定义 -->
<color name="bg_login">#FFFFFF</color>      <!-- 登录页背景 -->
<color name="bg_home">#F5F5F5</color>      <!-- 首页背景 -->
<color name="bg_profile">#FFFFFF</color>    <!-- 个人中心背景 -->
<color name="text_title">#141414</color>   <!-- 标题文字 -->
<color name="text_desc">#808080</color>    <!-- 描述文字 -->
<color name="text_hint">#BFBFBF</color>    <!-- 提示文字 -->
<color name="button_red">#DB121F</color>   <!-- 红色按钮 -->
<color name="red_button">#DB121F</color>   <!-- 另一个红色按钮 -->

1.2 问题分析

问题类型 具体表现 影响
重复定义 #FFFFFF 和 #DB121F 多次出现 改一处需改所有地方,容易遗漏
业务绑定 bg_login、bg_home 与具体页面绑定 无法复用,扩展性差
命名混乱 button_red 和 red_button 同时存在 新人难以选择,团队协作困难
夜间模式灾难 需复制所有颜色到 values-night 工作量巨大,容易出错

1.3 根本原因

这些问题的本质在于:颜色定义与业务语义、主题逻辑过度耦合。当一个颜色既承载了”背景”的业务含义,又承载了”白色”的具体色值时,任何改动都会牵一发而动全身。

二、三层颜色架构设计理念

针对这些问题,我设计了一套严格单向依赖的三层颜色架构:

2.1 架构核心原则

层级 唯一职责 命名规则 是否承载业务语义 修改频率
基础色层 定义原始色值 色系_数字(如 white_1) ❌ 否 极低(品牌升级时才改)
主题层 日间/夜间模式映射 t_色系_数字(如 t_white_1) ❌ 否 低(新增主题时才改)
功能色层 UI 职能封装(文本、背景、边框等) func_{色系}_{职能}_{档位}(如 func_black_text_1) ❌ 否 由设计师维护(新增档位/职能时改)

重要说明:功能色层封装的是 UI 职能(如文本、背景、边框),而非具体业务场景。func_black_text_1 代表黑色系主档文本色,可用于商品标题、页面标题、按钮文字等任何场景,不绑定具体业务。功能色的定义权归属设计师,研发只引用、不新增。

2.2 严格单向依赖规则

为什么必须严格遵守单向依赖?

  • 避免循环依赖导致的颜色定义混乱
  • 每层只做自己的事,职责清晰,便于定位问题
  • 改一处全局生效,维护成本极低
  • 多人开发不会互相冲突

三、分层详解:每一层该怎么设计

3.1 第一层:全局基础色层

定位:纯原始色值定义,不做任何主题绑定和业务关联

命名规则:色系_数字 下划线格式,数字按明度/饱和度递增

设计原则:

  • 白色系:数字越小越浅(white_1 = 纯白)
  • 黑色系:数字越小越浅(black_1 = 浅灰)
  • 彩色系:数字越小饱和度越低
  • 不参与日夜切换,保持绝对稳定

完整基础色表(与仓库实现一致):

色系 档位数 命名区间 / 说明
白色系 4 white_1 ~ white_4
黑色系 8 black_1 ~ black_8
灰色系 7 gray_1 ~ gray_7
红色系 4 red_1 ~ red_4
橙色系 4 orange_1 ~ orange_4;含 orange_0、orange_2b、orange_3b
黄色系 4 yellow_1 ~ yellow_4
蓝色系 4 blue_1 ~ blue_4
绿色系 4 green_1 ~ green_4
补间色 按需 如 black_5a
透明度变体 按需 基础色名_alpha{透明度}

代码示例:

<!-- ✅ 正确:统一色系_数字命名 -->
<color name="white_1">#FFFFFF</color>
<color name="black_8">#000000</color>
<color name="red_4">#DB121F</color>
<color name="black_1">#F0F0F0</color>
<color name="white_1_alpha20">#33FFFFFF</color>

3.2 第二层:主题适配层(t_)

定位:唯一的日夜模式映射层,只做色值代理,不承载任何业务语义

命名规则:t_基础色名,与基础色一一对应

设计原则:

  • 只引用基础色层变量,绝对不写具体色值
  • 日间/夜间模式通过 Android 资源限定符自动切换
  • 保持与基础色完全一致的命名,便于维护

错误做法(常见误区):

<!-- ❌ 错误:主题层承载了业务语义 -->
<!-- values/colors.xml -->
<color name="t_bg_page">#FFFFFF</color>
<color name="t_text_main">#000000</color>

<!-- values-night/colors.xml -->
<color name="t_bg_page">#141414</color>
<color name="t_text_main">#FFFFFF</color>

问题:主题层承载了业务语义,破坏了分层原则。新增主题时需要复制所有业务语义的颜色。

正确做法:

<!-- ✅ 正确:只做颜色映射,不关心用途 -->
<!-- values/colors_theme_tokens.xml(日间模式) -->
<color name="t_white_1">@color/white_1</color>
<color name="t_black_8">@color/black_8</color>
<color name="t_orange_4">@color/orange_4</color>

<!-- values-night/colors_theme_tokens.xml(夜间模式) -->
<color name="t_white_1">@color/black_8</color>   <!-- 背景色反转 -->
<color name="t_black_8">@color/white_1</color>   <!-- 主文字色反转 -->
<color name="t_orange_4">@color/orange_3b</color> <!-- 夜间使用较浅的橙色 -->

优势:

  • 主题层只做颜色映射,不关心用途
  • 新增主题只需要加一个资源目录
  • 夜间模式切换完全由 Android 系统自动处理,零代码侵入

3.3 第三层:功能色层(func_)

定位:面向 UI 职能的语义抽象层,不承载业务语义(如「登录页背景」「删除按钮红」)

命名规则:func_{色系}_{职能}_{档位},档位数字按该职能下的深浅/重要性递增

设计原则:

  • 只引用主题层变量,绝对不直接引用基础色
  • 采用「色系 × 职能 × 数字档位」模式,保留无限扩展能力
  • 由设计师在资源文件中定义与维护;研发在布局/代码中只引用已有 token

为什么我反对固定语义命名?

很多人喜欢这样定义功能色:

<color name="func_text_main">@color/t_black_8</color>
<color name="func_text_sub">@color/t_black_5</color>
<color name="func_text_aux">@color/t_black_3</color>

这在实际项目中会出问题:中间态越来越多,命名很快失控。比如需要一个介于 sub 和 aux 之间的颜色时,该叫 func_text_sub2 还是 func_text_medium?

最佳实践:色系 + 职能 + 数字档位

<!-- 黑色系文本:档位越小越深、越重要 -->
<color name="func_black_text_1">@color/t_black_8</color>
<color name="func_black_text_2">@color/t_black_7</color>
<color name="func_black_text_3">@color/t_black_5</color>
<color name="func_black_text_4">@color/t_black_3</color>

<!-- 黑色系背景:档位越小越浅 -->
<color name="func_black_bg_1">@color/t_black_8</color>
<color name="func_black_bg_2">@color/t_black_7</color>

<!-- 橙色系强调 -->
<color name="func_orange_text_1">@color/t_orange_4</color>
<color name="func_orange_bg_1">@color/t_orange_4</color>

无限扩展能力:

  • 需要在 func_black_text_2 与 func_black_text_3 之间加一档,由设计师新增 func_black_text_25 即可
  • 不用造 func_product_title 这类业务名
  • 规范可长期稳定

职能分类速览(详见第六节完整矩阵):

职能后缀 命名示例 典型用途
_text func_black_text_1 各级文字
_bg func_gray_bg_1 页面、卡片背景
_border func_gray_border_1 边框
_divider func_black_divider_1 分割线
_alpha func_black_alpha_1 遮罩、半透明
_shadow func_black_shadow_1 阴影

四、两个关键争议点的深度解析

4.1 争议1:主题层到底该不该承载业务语义?

我的答案:绝对不应该。

主题层的本质是颜色代理,它的唯一职责是根据当前主题返回对应的基础色。它不应该关心这个颜色是用来做背景还是文字。

如果主题层承载了业务语义:

  • 每新增一个主题,你都要复制所有业务语义的颜色
  • 业务语义变化时,你需要修改所有主题文件
  • 架构的解耦性被完全破坏

4.2 争议2:功能层用数字命名会不会可读性差?

不会,只要约定好规则。

我们只需要在团队内部约定:

  • 文本色:数字越小越重要、越深
  • 背景色:数字越小越浅
  • 边框色:数字越小越深

新人只需要花 5 分钟就能记住这些规则,比记住几十个不同的语义名称要容易得多。

五、核心优势:为什么这套架构能解决问题?

5.1 维护成本显著降低

改色流程对比:

操作 传统做法 三层架构
改品牌色 全局搜索替换几百个地方 修改基础色层一处
适配夜间模式 修改所有颜色定义 自动切换,零代码
新增页面 定义 5-10 个新颜色 复用设计师已定义的功能色

5.2 无限扩展能力

  • 新增色系:只需要在基础色层添加
  • 新增主题:只需要加一个资源目录
  • 新增 UI 职能档位:由设计师在功能层顺延数字编号

5.3 团队协作零成本

  • 统一的命名规范,没有歧义
  • 新成员 5 分钟就能上手
  • 多人开发不会互相冲突

六、功能色层详解:7大色系 × 6种职能

在实际项目中,我们发现一个 App 中常用的颜色职能只需要6种:

职能 用途 示例
文本色 文字显示 标题、正文、辅助文字
背景色 填充区域 页面背景、卡片背景
边框色 勾勒边界 输入框边框、卡片边框
分割线 分隔内容 列表分割线、区域分隔
透明度 半透明效果 遮罩、玻璃效果
阴影色 阴影效果 卡片阴影、按钮阴影

而这 6 种职能,组合7大色系,就构成了一个完整的颜色体系。

6.1 为什么是这7大色系?

色系 特点 主要用途
黑色系 从纯黑到浅灰的完整灰阶 正文、次要文字、背景
灰色系 独立的灰色梯度 辅助信息、禁用状态
红色系 高饱和度警示色 错误、删除、警告
黄色系 温和警示色 待处理、进行中
橙色系 强调色 热销、促销、主按钮
蓝色系 信任色 链接、信息、成功
绿色系 正向色 成功、增长、完成

6.2 完整颜色矩阵

文本色(7色系 × 4档 = 28个):

色系 命名 深浅/饱和度
黑色系 func_black_text_1 ~ func_black_text_4 1最深 → 4最浅
灰色系 func_gray_text_1 ~ func_gray_text_4 1最深 → 4最浅
红色系 func_red_text_1 ~ func_red_text_4 1高饱和 → 4低饱和
黄色系 func_yellow_text_1 ~ func_yellow_text_4 1高饱和 → 4低饱和
橙色系 func_orange_text_1 ~ func_orange_text_4 1高饱和 → 4低饱和
蓝色系 func_blue_text_1 ~ func_blue_text_4 1高饱和 → 4低饱和
绿色系 func_green_text_1 ~ func_green_text_4 1高饱和 → 4低饱和

背景色(7色系 × 2档 = 14个):

色系 命名 用途
黑色系 func_black_bg_1, func_black_bg_2 深色背景
灰色系 func_gray_bg_1, func_gray_bg_2 浅灰背景、卡片
红色系 func_red_bg_1, func_red_bg_2 错误背景
黄色系 func_yellow_bg_1, func_yellow_bg_2 警告背景
橙色系 func_orange_bg_1, func_orange_bg_2 强调背景
蓝色系 func_blue_bg_1, func_blue_bg_2 信息背景
绿色系 func_green_bg_1, func_green_bg_2 成功背景

边框色(7色系 × 2档 = 14个):

色系 命名 用途
黑色系 func_black_border_1, func_black_border_2 常规边框
灰色系 func_gray_border_1, func_gray_border_2 辅助边框
红色系 func_red_border_1, func_red_border_2 错误边框
黄色系 func_yellow_border_1, func_yellow_border_2 警告边框
橙色系 func_orange_border_1, func_orange_border_2 强调边框
蓝色系 func_blue_border_1, func_blue_border_2 信息边框
绿色系 func_green_border_1, func_green_border_2 成功边框

分割线、透明度、阴影色(各7色系 × 2档 = 各14个):

色系 分割线命名 透明度命名 阴影命名
黑色系 func_black_divider_1~2 func_black_alpha_1~2 func_black_shadow_1~2
灰色系 func_gray_divider_1~2 func_gray_alpha_1~2 func_gray_shadow_1~2
红色系 func_red_divider_1~2 func_red_alpha_1~2 func_red_shadow_1~2
黄色系 func_yellow_divider_1~2 func_yellow_alpha_1~2 func_yellow_shadow_1~2
橙色系 func_orange_divider_1~2 func_orange_alpha_1~2 func_orange_shadow_1~2
蓝色系 func_blue_divider_1~2 func_blue_alpha_1~2 func_blue_shadow_1~2
绿色系 func_green_divider_1~2 func_green_alpha_1~2 func_green_shadow_1~2

理论矩阵规模:7 色系 × 6 职能 × 2–4 档 ≈ 84 个 token,可覆盖绝大多数通用 UI 场景。本仓库 demo 仅实现常用子集(见 colors_semantic.xml);完整矩阵由设计师按产品需要逐步补齐,研发不自行「补色」。

6.3 核心原则:职能无关,业务通用

这套颜色体系是业务无关的。同一个 func_red_text_1:

  • 在电商 App 中可以用作「商品下架」提示
  • 在社交 App 中可以用作「被拉黑」提示
  • 在金融 App 中可以用作「交易失败」提示

颜色本身不承载业务语义,业务语义由使用场景决定。

6.4 反例 vs 正例

反例:业务绑定

<!-- ❌ 错误:业务绑定,无法复用 -->
<color name="func_product_delete_text">@color/t_red_5</color>    <!-- 商品删除文字 -->
<color name="func_order_cancel_text">@color/t_red_5</color>    <!-- 订单取消文字 -->

正例:职能无关

<!-- ✅ 正确:职能无关,业务通用 -->
<color name="func_red_text_1">@color/t_red_5</color>    <!-- 任何需要红色文字的地方 -->
<color name="func_red_text_2">@color/t_red_4</color>    <!-- 任何需要浅红文字的地方 -->

6.5 完整命名规范速查表

命名公式:func_{色系}_{职能}_{档位}

色系前缀:

前缀 色系 示例
black 黑色系 func_black_text_1
gray 灰色系 func_gray_text_1
red 红色系 func_red_text_1
yellow 黄色系 func_yellow_text_1
orange 橙色系 func_orange_text_1
blue 蓝色系 func_blue_text_1
green 绿色系 func_green_text_1

职能后缀:

后缀 职能 档位
_text 文本色 1-4档
_bg 背景色 1-2档
_border 边框色 1-2档
_divider 分割线 1-2档
_alpha 透明度 1-2档
_shadow 阴影色 1-2档

七、总结

这套三层颜色架构的核心思想其实很简单:解耦。

  • 把色值定义和主题适配解耦
  • 把主题适配和 UI 职能语义解耦(职能语义仍由设计师定义,不绑定具体业务页面)
  • 每一层只做自己最擅长的事

通过「7大色系 × 6种职能」的设计,我们构建了一套完整、可扩展、业务无关的颜色体系,覆盖 App 所有通用 UI 场景。

参考代码:

💡 如果你觉得这篇文章对你有帮助,欢迎点赞、收藏、转发。关注我,获取更多 Android 架构设计干货。

How to Prove AI ROI to a CFO Who Hates AI (5-Layer Method)

How to Prove AI ROI to a CFO Who Hates AI (5-Layer Method)

Originally published at korixinc.com.

How to Prove AI ROI to a CFO Who Hates AI (5-Layer Method)

Measuring AI ROI requires a 5-layer framework: direct cost reduction (hours saved, errors reduced), revenue acceleration (faster decisions, better targeting), risk avoidance (compliance costs prevented), capability premium (things now possible that were not before), and compound effects (improvements that accelerate over time). Most teams fail at ROI measurement not because AI is not delivering value, but because they only measure the first layer and ignore the rest.

You deployed an AI system six months ago. The engineering team says it is working well. But when your CFO asks “what is the return on this investment?” the room goes quiet. Not because the system is failing — but because nobody set up the measurement to answer that question. This is the most common failure mode in enterprise AI, and it kills more programmes than bad models do.

The problem is that traditional ROI calculation — (gain from investment minus cost of investment) divided by cost of investment — does not map cleanly to AI. AI creates value across multiple dimensions simultaneously: it reduces costs, accelerates revenue, avoids risks, enables new capabilities, and compounds improvements over time. If you only measure direct cost savings, you are presenting perhaps 30% of the actual value to your board. The other 70% is real, but invisible because you are not measuring it.

This article gives you a practical framework for measuring all five layers of AI ROI, with concrete formulas, realistic timelines, and a board presentation structure that translates AI performance into the financial language your executive team already speaks.

ROI Layer What to Measure Timeline
Direct Cost Reduction Hours saved, errors reduced, headcount freed 1-3 months
Revenue Acceleration Faster decisions, better targeting 3-6 months
Risk Avoidance Compliance costs avoided, incidents prevented 6-12 months
Capability Premium New capabilities that were previously impossible 6-12 months
Compound Effects Improvements that accelerate over time 12+ months

3–6 monthstypical timeline to measure meaningful AI ROIKORIX estimate

How to Measure AI ROI: A Framework for Enterprise Teams

Why most teams can’t prove AI ROI

ROI feels impossible because traditional metrics do not map cleanly to AI. When your finance team calculates ROI on a new warehouse, the formula is straightforward: increased throughput minus lease cost. When they try to calculate ROI on an AI document processing system, the value is spread across time savings, error reduction, compliance improvement, employee reallocation, and capabilities that did not previously exist. No single metric captures all of it.

Many teams fall back on the “AI is different” excuse. They argue that AI value is too diffuse, too long-term, or too qualitative to measure. This is wrong. AI is not different — it just needs different measurement. You would not measure the ROI of a sales team by counting the number of phone calls they make. You would measure the revenue they generate. The same principle applies to AI: measure outcomes, not activity.

Consider what happened with one operations-heavy client we worked with. They were manually processing several thousand documents monthly with multiple staff members and frequent data-entry errors. The process was expensive, slow, and error-prone — but nobody had ever quantified exactly how expensive, how slow, or how error-prone. After deploying AI extraction, processing time dropped significantly and accuracy improved measurably. The ROI calculation was straightforward: hours saved multiplied by hourly cost, plus error reduction multiplied by cost per error. But it was only straightforward because we had established the baseline before deployment. Without those pre-deployment numbers, the team would have been guessing.

The three structural reasons teams cannot prove AI ROI are consistent across organisations:

  • No baseline measurement. They never documented the cost, speed, and error rate of the process before AI. Without a “before” number, the “after” number is meaningless.
  • Single-dimension measurement. They measure only direct cost savings and miss the other four layers of value: revenue acceleration, risk avoidance, capability premium, and compound effects.
  • Technical language in financial conversations. They present model accuracy and processing speed to a board that thinks in cost per transaction and revenue per employee. The value is real, but the translation is missing.

If you are not sure whether your organisation has the data foundations needed for clean ROI measurement, an AI readiness assessment can identify the gaps before you deploy.

The baseline problem

If you did not measure the process before AI, you cannot prove AI improved it. Before any deployment, document: time per task, cost per unit, error rate, throughput, and headcount involved. These five numbers are the foundation of every ROI calculation that follows.

The KORIX AI ROI Framework: 5 layers

Most organisations measure only Layer 1 — direct cost reduction — and present that as the total AI ROI. This typically captures 20–40% of the actual value. The remaining value is real, measurable, and often larger than the direct savings. But it requires a structured approach to capture it.

The framework works in layers because AI value accumulates over time. Layer 1 is visible within weeks. Layer 5 may take twelve months or more to materialise. Boards that understand this layered timeline make better investment decisions because they are not judging a twelve-month programme by its three-month results.

Layer 1: Direct Cost Reduction

This is the most tangible layer and the one your CFO will scrutinise first. It includes three components: time saved (hours no longer spent on the task, multiplied by the hourly cost of the people who were doing it), headcount freed (staff who can be redeployed to higher-value work), and error reduction (the cost of mistakes that no longer happen).

Direct cost reduction is measurable within one to three months of deployment. It maps directly to operating costs, which makes it the easiest layer to present to a board. The formula is simple: (baseline cost per unit minus post-AI cost per unit) multiplied by volume.

Layer 2: Revenue Acceleration

AI does not just reduce costs — it accelerates revenue by enabling faster decisions, better targeting, and new commercial capabilities. A demand forecasting system that improves inventory accuracy also reduces stockouts, which means more sales. A lead scoring system that prioritises higher-converting prospects means more revenue per sales hour.

Revenue acceleration is harder to attribute cleanly than cost reduction, but it is often the larger number. The measurement approach is A/B comparison where possible: compare revenue from AI-assisted processes against a control group using the old process. Where A/B is not feasible, use before-and-after comparison with controls for seasonal and market factors.

Layer 3: Risk Avoidance

Risk avoidance measures the bad things that did not happen because AI was in place. Compliance violations prevented. Audit findings avoided. Security incidents caught before they escalated. Regulatory penalties not incurred. For organisations in regulated industries — financial services, healthcare, legal — risk avoidance is frequently the largest single layer of AI ROI.

The challenge with risk avoidance is that you are measuring a counterfactual: what would have happened without AI. The most credible approach is to use historical incident rates as the baseline. If your pre-AI compliance error rate was 3.2% and post-AI it dropped to 0.4%, the risk avoidance ROI is the expected cost of the prevented incidents. For governed AI systems with complete audit trails, this calculation becomes significantly more defensible.

Layer 4: Capability Premium

Capability premium captures the value of things you can now do that were previously impossible or impractical. An AI system that analyses customer sentiment across fifty thousand support tickets per month is not just doing what a human team did faster — it is doing something that was never feasible at that scale. The insight it generates has value that cannot be measured as cost reduction because no cost existed before.

Measuring capability premium requires asking: what decisions can we now make that we could not make before? What markets can we enter? What products can we offer? What response time can we achieve? The monetary value is the revenue or cost impact of those new capabilities.

Layer 5: Compound Effects

AI systems improve over time as they process more data. A document extraction model that is 92% accurate in month one may be 97% accurate in month six because it has learned from edge cases. A demand forecasting model gets more precise as it accumulates more historical patterns. This compounding effect means that the ROI measured in month three is not representative of the ROI in month twelve.

Compound effects are measured by tracking the same metrics over time and fitting a trend. If cost per transaction is dropping 8% month over month, that compounding rate is itself a valuable metric to present to the board. It demonstrates that the AI investment is not just delivering returns — it is delivering accelerating returns.

L1Direct Cost ReductionTime saved, headcount freed, errors eliminated — 1–3 monthsL2Revenue AccelerationFaster decisions, better targeting, new capabilities — 3–6 monthsL3Risk AvoidanceCompliance costs avoided, incidents prevented — 6–12 monthsL4Capability PremiumThings now possible that were not before — 6–12 monthsL5Compound EffectsAccelerating improvements over time — 12+ months

How to calculate each layer

Each layer has a specific calculation approach. The key is not precision — it is consistency. A conservative estimate that you track monthly is far more valuable than a precise estimate that you calculate once and never update. Boards trust trends more than snapshots.

Layer 1 formula: Direct Cost Reduction

Monthly savings = (baseline hours per task − current hours per task) × tasks per month × fully loaded hourly cost

Add to this: (baseline error rate − current error rate) × volume × average cost per error. The “fully loaded hourly cost” should include salary, benefits, overhead, and management time — not just the base hourly rate. Most organisations undercount this by 30–50% because they use base salary instead of total cost of employment.

Layer 2 formula: Revenue Acceleration

Revenue uplift = (AI-assisted conversion rate − baseline conversion rate) × opportunity volume × average deal value

Where A/B testing is not possible, use: (post-deployment revenue − projected baseline revenue, adjusted for market factors) × AI attribution percentage. The attribution percentage is a judgment call — be conservative. A 40–60% attribution to AI for improvements in AI-assisted workflows is a credible starting point.

Layer 3 formula: Risk Avoidance

Risk avoidance = (historical incident rate − current incident rate) × average cost per incident

Include in “cost per incident”: regulatory penalties, audit costs, remediation effort, customer compensation, and reputational damage where quantifiable. For industries where a single compliance failure can cost six or seven figures, this layer often justifies the entire AI implementation cost on its own.

Layer 4 approach: Capability Premium

Capability premium does not have a clean formula because it measures net-new value. The approach is to identify each new capability AI enables and estimate its commercial value: new revenue streams opened, market segments now addressable, response times now possible, analysis depths now feasible. Track these as a portfolio of capability-driven outcomes.

Layer 5 approach: Compound Effects

Track any Layer 1–4 metric monthly and calculate the month-over-month improvement rate. If cost per transaction is dropping 5–10% per month consistently, that compound rate is itself a powerful board metric. Project the compound trajectory forward to show the board what the 12-month and 24-month ROI looks like if the trend holds.

Layer What to Measure How to Measure Timeline
L1: Direct Cost Reduction Hours saved, errors reduced, headcount freed (Baseline − current) × volume × cost 1–3 months
L2: Revenue Acceleration Conversion lift, deal velocity, new revenue A/B test or before/after with attribution % 3–6 months
L3: Risk Avoidance Incidents prevented, compliance maintained (Historical rate − current rate) × cost per incident 6–12 months
L4: Capability Premium New capabilities, markets, response times Portfolio of capability-driven revenue/savings 6–12 months
L5: Compound Effects Month-over-month improvement rate Trend analysis across L1–L4 metrics 12+ months

The biggest ROI mistake

The biggest ROI mistake is measuring too early. AI systems improve over time as they learn from more data. A system measured at month one will underperform the same system measured at month six. Set expectations with your board for a 3–6 month measurement window before drawing conclusions about long-term ROI.

150–300%estimated ROI range for well-executed AI implementations over 3 yearsSource: industry estimates (McKinsey, 2025)

The board presentation framework

Your board does not want to understand AI. They want to understand what AI is doing to the numbers they already track. The most effective AI ROI presentations never mention model architecture, training data, or inference speed. They present before-and-after comparisons in the financial language the board already uses.

What boards actually want to see

In our experience across multiple client board presentations, executives consistently prioritise three things: how much is this saving us (Layer 1), how much more revenue is it generating (Layer 2), and what risks is it reducing (Layer 3). Layers 4 and 5 are strategic context that supports continued investment — they are important but secondary to the financial headline.

The structure that works is a one-page summary with four sections:

  • Headline metric: Total ROI as a single number or ratio (e.g., “3.2x return on AI investment year-to-date”)
  • Before/after comparison: Three to five key metrics showing the pre-AI baseline versus current performance
  • Layer breakdown: How the total ROI splits across the five layers, showing which types of value are materialising
  • Trajectory: Month-over-month trend showing whether ROI is accelerating, stable, or declining

Before/after metrics that work

An e-commerce company we worked with needed AI demand forecasting across hundreds of SKUs. Their data lived in three disconnected systems — sales history in one platform, supplier lead times in another, marketing calendar in a spreadsheet. After building a unified data structure and deploying AI, inventory accuracy improved measurably within three months. Stockouts dropped. Overstock write-offs fell. The board presentation wrote itself: cost per unit of inventory holding before versus after, with clear cost attribution to the AI system.

The before/after format works because it requires no AI knowledge to interpret. Your CFO does not need to understand what a demand forecasting model does. They need to see that inventory holding cost dropped from X to Y, and that the drop is attributed to the AI system deployed in a specific month. That is a financial conversation, not a technical one.

The 1-page AI ROI summary structure

For each AI use case in production, maintain a living one-page document with this structure:

  • Use case name and deployment date
  • Baseline metrics (pre-AI, documented with date)
  • Current metrics (latest month)
  • Delta (improvement in absolute numbers and percentage)
  • Financial impact (delta translated into monetary value per month and cumulative)
  • Total cost of ownership (monthly AI operating cost including infrastructure, monitoring, and staff time)
  • Net ROI (financial impact minus total cost of ownership)
  • Trend (is the ROI improving, stable, or declining month over month?)

This single page, updated monthly, gives the board everything they need to evaluate and justify AI investment. It takes perhaps two hours per month to maintain once the instrumentation is in place. If you are considering whether your organisation is ready for this kind of structured measurement, check the 7 signs you are ready for AI.

The best board presentation is the one that could be understood by someone with zero AI knowledge. If your CFO needs a glossary to read your ROI report, the report is wrong.

Common ROI measurement mistakes

These five mistakes are not theoretical — they are patterns we see repeatedly in organisations that struggle to justify continued AI investment. Each one is avoidable with the right measurement structure in place from the start.

Mistake 1: Measuring too early

AI systems improve over time. A document processing model that is 91% accurate in week two may be 96% accurate in month four because it has been retrained on edge cases your data surfaces. Measuring ROI in the first month and extrapolating to a year produces an underestimate that can kill a programme that would have delivered strong returns by month six. Set the board’s expectations for a 3–6 month measurement window before drawing conclusions.

Mistake 2: Counting only direct savings

If your ROI calculation includes only Layer 1 (direct cost reduction), you are presenting a fraction of the real value. A compliance AI system might save 2,000 per month in direct processing time (Layer 1). But it also prevents compliance incidents that historically cost 50,000 each (Layer 3) and enables the compliance team to take on new regulatory requirements they previously lacked capacity for (Layer 4). Presenting only the 2,000 makes the investment look marginal when it is actually transformative.

Mistake 3: Ignoring the counterfactual

The counterfactual is: what would have happened without AI? If your industry is experiencing a skills shortage and your manual process was already struggling before AI, the relevant comparison is not “AI cost versus current process cost” — it is “AI cost versus the cost of the process degrading further without AI.” Some AI investments prevent deterioration rather than improve on a stable baseline. That prevention value is real ROI, but you have to measure it explicitly.

Mistake 4: Using vanity metrics

Model accuracy is not business value. A model that is 98% accurate on a low-stakes task generates less business value than a model that is 90% accurate on a high-stakes task. The metric that matters is not how accurate the AI is — it is what the accuracy produces in financial terms. Always translate technical metrics into their financial consequences: “98% accuracy means 2% of transactions require manual review, costing approximately X per month.”

Mistake 5: Not attributing compound effects

When your AI system gets better every month, that compounding improvement is itself a form of value that most organisations never quantify. If processing cost is dropping 6% per month due to continuous learning, that trajectory is worth presenting to the board. It shows that the AI investment is not just delivering returns — it is delivering accelerating returns. A flat ROI justifies maintenance. An accelerating ROI justifies expansion.

The attribution rule

When in doubt, be conservative with attribution. A board that sees a conservative ROI estimate they trust is more likely to approve expansion than a board that sees an optimistic estimate they question. Credibility compounds in the same way that AI accuracy does.

When AI ROI is genuinely hard to prove

Not every AI project has a clean ROI calculation. Some projects deliver value that is real but structurally difficult to quantify. Acknowledging this honestly — rather than forcing every project into a dubious ROI framework — is itself a sign of measurement maturity.

Exploratory AI projects

Research and exploration projects — testing whether AI can solve a problem you are not yet sure is solvable — have uncertain ROI by definition. The appropriate framework here is not ROI but expected value: the probability of success multiplied by the value of success, minus the cost of the exploration. If a three-month exploration costs 30,000 and has a 40% chance of unlocking a capability worth 500,000 annually, the expected value is positive even if four out of ten explorations fail.

Governance and compliance AI

Governance AI is a particular challenge because its primary value is preventing bad outcomes rather than creating good ones. A financial services firm we worked with automated document analysis for loan applications. The ROI was not just processing speed — it was regulatory compliance maintained at scale. Compliance officers could trace every AI recommendation back to the source data and the decision logic. That traceability meant auditors could review decisions faster, audit preparation time dropped from hundreds of hours to a fraction of that, and the risk of audit findings decreased measurably.

That is risk avoidance ROI: the cost of the audit you did not fail, the penalty you did not receive, the remediation you did not need. It is real value, but it requires comparing against a counterfactual — what would have gone wrong without the governed AI system in place.

The honest approach

For AI projects where ROI is genuinely difficult to quantify, the most credible approach is layered honesty:

  • Layer 1 (direct savings): Present the hard numbers you can prove
  • Layers 2–3 (revenue and risk): Present conservative estimates with clear assumptions stated
  • Layers 4–5 (capability and compound): Present qualitative descriptions of the strategic value, without forcing a number

A board that sees honest layering — some numbers you are confident in, some estimates you are transparent about, and some qualitative value you describe without inflating — trusts the entire presentation more than a board that sees a single inflated number they cannot verify.

If you are evaluating whether AI is right for your specific situation, our 21-Day AI Pilot is designed specifically to generate real ROI data from your own processes before you commit to full deployment. The pilot gives you Layer 1 numbers you can take to your board with confidence.

The Bottom Line

Stop measuring one layer.
Start measuring all five.

AI ROI is not a single number — it is five layers of value that materialise at different speeds. Direct cost reduction is the starting point, not the whole picture. Revenue acceleration, risk avoidance, capability premium, and compound effects are where the majority of AI value lives. Measure all five, present them honestly, and your board will see AI as an investment, not an expense.

FAQ

Common questions about

measuring AI ROI.

Have a question not listed here?

Ask us directly →

How long does it take to see ROI from AI?

Most organisations see initial measurable results within 3 to 6 months of production deployment. A well-scoped 21-day pilot can demonstrate validation ROI even sooner. Strategic ROI — competitive advantage and new capabilities — typically emerges at the 6 to 12 month mark. The key is setting realistic expectations for each phase.

What is the average ROI of AI implementation?

Industry estimates suggest 150 to 300 percent ROI over three years for well-executed implementations (Source: McKinsey, 2025). However, this varies enormously by use case. Process automation tends to deliver faster returns than exploratory projects. The most reliable estimate comes from running a pilot on your specific process and extrapolating from measured results.

How do you calculate AI ROI?

Calculate across five layers: direct cost reduction (hours saved × hourly cost + errors reduced × cost per error), revenue acceleration (conversion uplift × deal value), risk avoidance (incidents prevented × cost per incident), capability premium (value of new capabilities), and compound effects (month-over-month improvement trajectory). Sum all five for complete ROI.

Can you measure AI ROI before deployment?

Yes, via a pilot. A 21-day AI pilot gives you real performance data from your own processes. By establishing baseline metrics before the pilot and measuring against them during, you get a credible ROI projection based on actual results rather than vendor estimates. This is significantly more reliable than pre-deployment forecasting based on industry benchmarks alone.

What are the hidden costs of AI that affect ROI?

Hidden costs include: data preparation and cleaning (often 40–60% of project effort), integration with existing systems, staff training and change management, ongoing model monitoring and retraining, governance and compliance overhead, and the operational owner’s time for maintenance. A realistic ROI calculation subtracts total cost of ownership, not just the initial build cost. See our guide on AI implementation costs for a complete breakdown.

tmux: Persistent Terminal Sessions for Developers

I lost three hours of work to a dropped SSH connection before I learned about tmux. One detached session later and that problem stopped existing entirely. If you spend any meaningful time on remote servers, tmux is the single highest-leverage tool you can add to your workflow.

Two things make it worth learning: sessions survive after you close your terminal or lose an SSH connection — your processes keep running and you reconnect to find everything exactly where you left it. And you can split a single terminal into multiple panes and windows without juggling tabs.

Install

# Debian / Ubuntu
sudo apt install tmux

# RHEL / Fedora / Rocky
sudo dnf install tmux

# macOS
brew install tmux

Core concepts

tmux has three levels:

  • Session — a collection of windows. One session per project is the natural fit.
  • Window — a full-screen view inside a session. Think of it like a browser tab.
  • Pane — a split region within a window. One window can hold several panes.

The prefix key is how you send commands to tmux without the keystrokes going to the program running inside it. The default is Ctrl+B. Press it, release, then press the command key.

Start and attach to sessions

Create a new named session:

tmux new -s myproject

Detach (session keeps running in the background):

Ctrl+B  d

List sessions:

tmux ls

Reattach by name:

tmux attach -t myproject

Short form: tmux a -t myproject. With only one session, tmux a is enough.

Kill a session:

tmux kill-session -t myproject

Windows

Action Keys
New window Ctrl+B c
Next window Ctrl+B n
Previous window Ctrl+B p
Go to window by number Ctrl+B 0–9
Rename current window Ctrl+B ,
Close current window Ctrl+B &

Windows appear in the status bar at the bottom. The active one has a * next to its name.

Panes

Action Keys
Split top/bottom Ctrl+B "
Split left/right Ctrl+B %
Move between panes Ctrl+B arrow keys
Resize pane Ctrl+B Ctrl+arrow keys
Zoom to full screen Ctrl+B z (toggle)
Close current pane Ctrl+B x

Zoom is one of the most useful shortcuts — it temporarily expands a pane to fill the entire window without closing the others. Hit it again to return to the split view.

Scrollback and copy mode

Mouse scroll does not work inside tmux by default. To scroll:

Ctrl+B  [

This enters copy mode. Arrow keys and Page Up/Page Down navigate. Press / to search, n for the next match, q to exit.

Auto-start a session on login

tmux sessions do not survive a reboot. For development machines where you always want a session waiting:

# add to ~/.bashrc or ~/.zshrc
if [ -z "$TMUX" ]; then
  tmux attach -t main 2>/dev/null || tmux new -s main
fi

The [ -z "$TMUX" ] guard prevents tmux from launching inside an existing tmux session, which would nest them.

~/.tmux.conf

A minimal config that most people find immediately useful:

# Start window and pane numbering at 1 instead of 0
set -g base-index 1
setw -g pane-base-index 1

# Enable mouse: click to focus panes, drag to resize
set -g mouse on

# Increase scrollback
set -g history-limit 10000

# Status bar: show session name on the left, time on the right
set -g status-left "[#S] "
set -g status-right "%H:%M"

Reload the config without restarting:

Ctrl+B  :source-file ~/.tmux.conf

Mouse support is the single option worth enabling immediately if you are used to a GUI terminal. It makes pane navigation and resizing click-based while you build up the keyboard shortcuts.

Found this useful? SysEmperor has more Linux tutorials and free developer tools — including a Cron Visual Editor, fstab Editor, and a growing library of downloadable AI skills at sysemperor.com.

People, Content, Community: Why AI Flips the Product Model from Factory to Playground

Every founder building a “community” product has felt this dissonance.

You launch. People come. They consume content. They leave. You pump out more content. They scroll. They leave again. You have a content platform, maybe a newsletter, maybe a Discord that went quiet after week three. But you don’t have a community.

This isn’t a failure of execution. It’s a failure of definition.

A recent essay from Mingyeji (明夜集) by Wang Yizhou nails the distinction with a five-element framework that I haven’t been able to stop thinking about. Let me unpack it, then show why AI fundamentally rewrites the rules.

The Five Elements That Make a Community

Most products labeled “community” are just chat rooms with content feeds. Here’s the test:

Element What it means When it’s missing
Role A user can be recognized as someone specific by others Everyone is just “user #10482”
Action Each role has a unique way to contribute Everyone can only like/comment
Status/Incentive Contributions earn reputation, influence, or resources Pure passion labor, no reward loop
Hierarchy Layers with progression paths and mobility Flat structure, no sense of growth
Culture Boundary An identity barrier that creates belonging Anyone can join, no one cares

A community is not a group of people talking. It’s a value exchange system where users play recognized roles, perform specific actions, and climb a hierarchy within a bounded culture. Miss any of the five, and what you have is a content farm with comments.

The Inevitable Trajectory: Every Community Becomes a Content Platform

Here’s the painful truth the essay articulates: when a community breaks out, it becomes a content platform.

Bilibili started as a hardcore anime community with strict danmaku etiquette (a real hierarchy system). It broke out and became “China’s YouTube” — content replaced relationships as the core consumption unit. Xiaohongshu (Little Red Book) started as a overseas shopping community. It broke out and became a lifestyle content platform.

The transition isn’t a bug. It’s structural. Communities are small, high-friction, and deeply rewarding. Content platforms are large, low-friction, and shallow. Every community that scales hits this wall.

The question isn’t “can my community avoid becoming a content platform?” It’s “what survives from the community after it becomes one?”

AI Flips the Seed Unit from “Completed” to “Editable”

Every content platform has a seed unit — the smallest replicable atom of value that users produce and consume.

Platform Seed Unit Type
Twitter/X 140 characters Completed
Instagram Photo Completed
YouTube Video Completed
Live streaming Danmaku/comment Open
AI character platforms Conversation/state Open

For the last twenty years, nearly every product was built on completed seed units — articles, images, videos. The user produces. The platform distributes. The consumer scrolls.

Live streaming’s danmaku (bullet comments) cracked this open. Danmaku isn’t content — it’s proof of presence. It’s co-participation, not co-production. And it pointed toward a different kind of seed unit: one that can be edited, remixed, and forked.

This Is Where AI Changes Everything

The essay makes a claim I now fully endorse:

AI’s real superpower isn’t generation. It’s Editability.

Generative AI turns everything — characters, worlds, settings, storylines — into objects that can be continuously edited, inherited, and forked without breaking coherency. It makes Remix scalable.

Create vs. Remix:

  • Create = make something from nothing (high barrier)
  • Remix = edit something with context preserved (low barrier)

Before AI, remix at scale was impossible because context degraded. Pass a character through 100 human hands, and they become 100 different people. Pass a character through an AI-mediated pipeline, and the personality, memory, and voice stay consistent across forks.

This unlocks something that previously only existed in niche subcultures.

What Open Source Taught Us About Collaborative IP

The essay draws a brilliant analogy: open source collaboration patterns applied to IP creation.

Open Source Mechanism Applied to Collaborative IP
Protected main branch A maintained “canon” version of the character/world
Fork + PR Users fork alternate universe (AU) versions; good ones get merged back
Standardized protocols Fork/adopt/co-create/consensus conventions
Maintainer role Character “stewards” who curate canon
Reputation system Contributors earn naming rights, revenue share, voting power

This isn’t theoretical. Fandom and doujin circles have been running this model for decades. They already have:

  • Shared worlds with consistent lore
  • OC (Original Character) creation that other creators adopt
  • Tag systems, convention deadlines, collaborative anthologies
  • A clear hierarchy from “newbie” to “big name fan”

AI doesn’t invent the model. AI makes it operable at scale.

The Product Model That Emerges: Playground, Not Factory

The essay converges on a single metaphor: the Playground.

Dimension Traditional Content Platform Playground
Operational rhythm Publish → done Open daily, continuous
Space structure Platform decides the feed Platform builds infrastructure, users decide how to play
Goal Users consume content Users exist in a group
Barrier Low to enter, shallow depth Low to enter, unlimited depth
Repeat behavior Scroll more Return because the game gets deeper
Business model Ads + subscriptions Tickets + activity fees + merch

The Shift from Consumer to Participant

Dimension UGC Era AI Era Playground
Form Consume completed content Be present in an open experience
Output Consumption ends the cycle Consumption itself produces characters, relationships, positions
Example Watch video, like, leave Stay in an AI character’s room, build connections, create derivative work

The playground doesn’t turn consumers into producers. It turns scrolling into presence.

The Full Chain

Find a crowd (people who want to remix)
  → Build community (roles + cultural boundary)
  → Design collaborative mechanisms (fork/adopt/co-create)
  → Let collaboration produce assets (character IP + collective memory)
  → The product is now a playground, continuously operated

What This Means for Product Builders

If you’re building something with “community” aspirations, this framework suggests a different starting point:

Start with culture, not features. The five elements aren’t features you add later. Role, hierarchy, and cultural boundary must be there from the start, or they never materialize.

Design for remix, not consumption. Ask: can a user take what exists and edit it? Can they fork a character, a storyline, a setting? If the answer is no, you’re building a content platform, not a playground.

Measure presence, not views. The right metric for a playground is not DAU or time-on-site. It’s “how many users became someone here” — created a role, built a reputation, entered a hierarchy.

Three Questions That Don’t Have Answers Yet

The essay ends with questions I find more valuable than any conclusion:

  1. Can cross-user-consensus IP emerge from zero in the AI era? Fandom pulls it off because there’s a pre-existing canon. Has anyone built a shared IP from scratch through collaborative creation? No successful precedent yet.

  2. How do users from different playgrounds meet? Walled gardens? Inter-park passes? Or do they never intersect?

  3. What does it mean to “become” someone in an AI product? Not what users do, but who they become. This might be the hardest and most important question of all.

This essay was inspired by and engages with “People, Content, Community (Part III)” by Wang Yizhou from Mingyeji (明夜集). The original analysis of community’s five elements, the seed unit framework, and the playground metaphor are drawn from that work, extended here with the application to AI-era product design.

ADaaS Explained: The 2026 Model Replacing AI Consulting

ADaaS Explained: The 2026 Model Replacing AI Consulting

Originally published at korixinc.com.

ADaaS Explained: The 2026 Model Replacing AI Consulting

Agent Deployment as a Service (ADaaS) is a delivery model where a specialist firm deploys working AI agents directly into your production environment — no strategy decks, no multi-month discovery phases, no implementation left to you. The shift from traditional AI consulting to ADaaS is the most significant commercial change in the AI services market heading into 2026, and it is being driven by one simple buyer frustration: paying five figures for a roadmap you then have to build yourself.

This article explains what ADaaS is, why the traditional consulting model is breaking down, which buyer profile belongs in each camp, and how to evaluate whether an ADaaS provider is the real thing or just a consultant with better branding.

The Consulting Output Problem

Ask any operator who has hired an AI consultancy in the last two years what they received. The honest answer, more often than not, is a presentation.

Sometimes it is a “strategic roadmap.” Sometimes it is a “technology assessment.” Sometimes it is a detailed implementation guide with vendor recommendations. What almost never comes out of it is a working system sitting inside the business doing actual work.

This is not a failure of intelligence on the consultant’s part. It is a structural feature of how consulting is designed. Consulting firms bill for analysis, frameworks, and recommendations. Execution is a different engagement — often with a different team, a different commercial arrangement, and a different timeline that starts from scratch.

The McKinsey State of AI report has consistently found that the gap between AI ambition and AI deployment remains wide across industries. Organisations report high interest in AI but substantially lower rates of production deployment. That gap has a name: implementation debt. Businesses accumulate strategy they cannot execute.

The pattern is consistent. A company spends three to six months in discovery and design with a consulting firm. They receive recommendations. Internal teams — already stretched — are asked to carry the build. The build stalls. The budget is exhausted. The AI initiative is quietly deprioritised. Eighteen months later, a new consultancy is brought in to “reassess the landscape.”

Buyers in 2026 are starting to refuse this cycle. They want agents in production, not advice about agents.

The “Strategy First” Trap

Some providers use “strategy phase” language to describe what is effectively a paid scoping exercise with no deployment obligation. Before signing any AI services contract, confirm in writing whether the engagement ends with a working system or a document. If the answer is a document, you are buying consulting, not deployment.

What Agent Deployment as a Service Actually Covers

ADaaS is not a rebranded consulting retainer. It is a fundamentally different commercial structure with different inputs, outputs, and risk allocation.

A genuine ADaaS engagement includes:

  1. A scoped, time-bounded discovery — typically one to five days, not months. The goal is to identify the highest-leverage deployment target, not to map your entire enterprise AI strategy.
  2. Agent build in a real environment — agents are built against your actual stack, your actual data, and your actual workflows. Not a sandbox. Not a demo environment.
  3. Deployment to production — the agent goes live before the engagement closes. Deployment is not a future milestone; it is the contractual deliverable.
  4. Ownership transfer — you own the code, the logic, and the configuration. There is no ongoing licence fee to access what was built for you.
  5. Guardrails and observability — any responsible ADaaS provider builds in monitoring, logging, and override capability from day one. Governed AI practices are not optional extras; they are built into the deployment.

What ADaaS does not cover is enterprise transformation strategy, change management programmes, or vendor evaluation for large-scale platform decisions. Those are legitimate consulting needs — they just belong in a different commercial model.

The distinction matters because it determines where the risk sits. In consulting, the risk of a recommendation not working sits with you. In ADaaS, the risk of the agent not working sits with the provider. That is a fundamentally different incentive structure.

The Deliverable Test

Apply this test to any AI services proposal: what is the deliverable on the final day of engagement? If the answer is a document, a presentation, or a set of recommendations, you are buying consulting. If the answer is a working system processing real data inside your business, you are buying deployment. The deliverable test will save you more money than any due-diligence checklist.

Why 2026 Is the Inflection Point

Three forces converged to make ADaaS commercially viable at scale in 2026, and understanding them helps you evaluate whether a provider is ahead of the curve or still operating on 2022 assumptions.

Agents matured past prototype. The tooling for building production-grade AI agents — orchestration frameworks, reliable API ecosystems, vector databases, observability layers — reached a level of stability in 2024-2025 that makes 21-day deployments feasible where they were not before. The Stanford HAI AI Index 2025 documented the sharp acceleration in agent capability benchmarks across reasoning, tool use, and multi-step task completion. What required a research team in 2022 can be shipped by a focused engineering team in weeks today.

Buyer sophistication increased. The Gartner Hype Cycle for AI noted the market moving through peak inflated expectations. Buyers who went through a failed AI initiative in 2023 or 2024 have scar tissue. They ask sharper questions. They push back on vague timelines. They want contractual milestones tied to working software, not phase completions.

The consulting supply problem. Major consultancies cannot deploy at the speed or specificity that small and mid-size service businesses need. Their commercial model requires large contracts to justify partner-level attention. A 30-person professional services firm does not get the same team as a FTSE 500. ADaaS providers, built specifically for the 20-150 staff segment, can be more responsive, more specific, and more accountable.

“AI is the new electricity. It’s going to transform every industry. But the bottleneck isn’t the technology anymore — it’s deployment.” — Andrew Ng, Founder of DeepLearning.AI

The Deloitte AI Institute has similarly reported that organisations with dedicated deployment capability — as opposed to those relying solely on strategic guidance — show markedly faster time-to-value from AI investments. The pattern holds: advice without execution is the bottleneck, not the ambition.

If you are unsure whether your business is ready for deployment rather than strategy, the AI readiness assessment takes under two minutes and tells you where you actually sit.

The ADCO Framework: Four Stages of ADaaS Maturity

To help buyers evaluate providers and plan their own progression, KORIX uses the ADCO Framework — a four-stage model that maps the maturity of an Agent Deployment as a Service engagement.

1. Assess A time-bounded diagnostic of your existing stack, your highest-friction workflows, and the deployment targets most likely to return value within 30 days. Assessment output is a deployment brief, not a strategy document. The brief names the agent, the trigger, the integration point, and the success metric. Duration: one to five days.

2. Deploy The agent is built, tested, and pushed to production against your real environment. This is the stage that traditional consulting omits or defers. In a well-run ADaaS engagement, Day 1 of Deploy follows immediately after Assessment. Duration: seven to 21 days depending on complexity.

3. Calibrate The first two to four weeks after go-live are calibration, not maintenance. Edge cases surface. Threshold adjustments are made. Monitoring confirms the agent is behaving as designed. Calibration is included in the engagement, not billed as a separate phase. Duration: two to four weeks post-deployment.

4. Own Ownership transfer is explicit and complete. You receive the code, the documentation, the environment configuration, and a handover session. Your team can modify, extend, or replace the agent without returning to the provider. The provider’s engagement ends at Own; there is no lock-in, no licence, no ongoing dependency.

This framework is the commercial inverse of how consulting typically operates. Consulting firms generate recurring revenue from ongoing engagement. The ADCO model generates referrals and reputation from clean exits — clients who got what they needed, own it outright, and come back when they are ready for the next agent.

Agent Deployment as a Service: The 2026 Model That Replaced AI Consulting

Agent Deployment as a Service: The 2026 Model That Replaced AI Consulting — at a glance.

ADaaS vs Traditional AI Consulting: A Direct Comparison

The market for AI services in 2026 includes a range of providers, and not all of them are honest about which model they are operating. The table below compares the primary categories on dimensions that matter to a 20-150 staff buyer.

Provider Model Primary Deliverable Time to Production Code Ownership Risk Location Typical Engagement Size
Big-4 AI Consulting (e.g. Deloitte, PwC, KPMG) Strategy roadmap + vendor recommendation 6-18 months Client builds separately Buyer £150k-£1M+
Boutique AI Strategy Firm Framework + playbook 3-6 months Buyer implements Buyer £25k-£150k
SaaS AI Platform (e.g. no-code tools) Platform access + templates Weeks (template), months (custom) Vendor retains IP Split £500-£5k/month recurring
Staff Augmentation / AI Freelancer Individual contributor capacity Depends on internal direction Buyer (if contracted correctly) Buyer Day rate, open-ended
Agent Deployment as a Service (e.g. KORIX) Working agent in production 7-21 days Client owns code outright Provider £8k-£50k fixed

The SaaS route is worth a separate note. No-code AI platforms have made it possible for non-technical teams to build basic automations without engineering support. For simple, low-stakes workflows, that is often the right answer. But when the workflow involves sensitive data, complex integrations, or business-critical decision-making, a platform’s template library hits its ceiling quickly. The build vs buy decision framework explains where that ceiling typically sits.

The Buyer Profile Each Model Serves

Not every business needs ADaaS, and being honest about that matters. The wrong model is expensive regardless of which direction the mismatch runs.

When Traditional Consulting Is the Right Answer

If your business has 500+ staff and is evaluating a multi-system AI transformation across departments, a consulting firm with change management capability is the appropriate choice. The complexity of stakeholder alignment, procurement, and governance at enterprise scale genuinely requires a strategic layer that ADaaS providers are not built to deliver.

Similarly, if your business has not yet identified a specific operational problem — if you are in “we should probably do something with AI” territory — a light-touch advisory engagement to structure your thinking is more useful than jumping to deployment. The 7 signs your business is ready for AI is a practical starting point for that self-assessment.

When ADaaS Is the Right Answer

ADaaS fits a specific and well-defined buyer:

  • 20-150 staff service businesses where the founder or ops lead can name a specific, painful, repetitive process
  • Existing software stack that works and does not need replacement — the agent connects to what is already there
  • Time pressure — the business cannot wait six months for strategy to turn into execution
  • Ownership preference — the buyer wants an asset, not a subscription to a capability

The BYOS philosophy — Bring Your Own Stack — is foundational here. Businesses that already run on functional software (CRMs, project management tools, email, document systems) are ideal ADaaS candidates because the integration surface is well-defined. Agents slot in alongside existing tools rather than replacing them.

Anna Mazurowska at Numerology-Matrix is a direct example of this profile. Her business had a clear, painful bottleneck: each client reading took three to four hours of manual work. The process was defined. The inputs and outputs were known. The bottleneck was execution capacity, not strategic direction. The KORIX engagement automated that process to eight minutes per client — a 95% time reduction and an 8x capacity increase — because the deployment target was specific and the existing workflow was understood before a line of code was written.

“They thought like product partners, not just developers.” — Anna Mazurowska, Founder, Numerology-Matrix. [Published Clutch review]

That framing — product partner rather than consultant — is the operational distinction that separates ADaaS from advisory work. A product partner cares whether the thing works in production. A consultant cares whether the recommendation was defensible.

How to Evaluate an ADaaS Provider (And Spot the Fakes)

The term “Agent Deployment as a Service” is new enough that it has not yet been diluted by providers who deliver consulting under the label. But that will change. Here is what to test.

Ask for production evidence, not demos. A legitimate ADaaS provider can show you agents running in production for real clients, not sandbox demos built for sales calls. Ask specifically: “Can you show me an agent you deployed in the last 90 days that is still running in a client’s production environment?” If the answer is a pivot to a demo, that tells you something.

Ask who owns the code on Day 22. The answer should be unambiguous: the client owns the code, the configuration, and the documentation, with no ongoing licence dependency. If the provider hedges, or if ownership is conditional on a continuing relationship, you are looking at a SaaS product dressed as a service.

Ask what happens if it does not work. A provider confident in their deployment capability will have a clear answer to this — either a guarantee structure, a partial-refund policy, or a defined remediation process. Vague answers about “working together to resolve issues” are not guarantees. KORIX’s 21-Day AI Pilot includes an explicit production guarantee: if a working system is not in production by Day 22, the second invoice is not owed and the client keeps everything built. That is a concrete commitment.

Check the stack philosophy. A provider who immediately recommends a new platform you have to purchase, or who requires you to migrate your data to their environment, is not operating an ADaaS model — they are operating a platform sale with services attached. The right provider works inside your existing stack. The BYOS philosophy exists specifically to protect clients from unnecessary platform dependency.

Review their failure literacy. Ask the provider to describe a deployment that did not go as planned and what they did. Providers who have only success stories either have not deployed enough or are not being honest. The common AI failure modes piece covers the patterns that separate avoidable failures from genuine complexity — a good provider will be fluent in all of them.

The partner evaluation guide covers additional due-diligence dimensions if you are shortlisting multiple providers. The AI implementation cost guide sets commercial benchmarks so you can assess whether pricing is consistent with the model being offered.

“ADaaS Is Just a Faster Version of Consulting”

Speed is a by-product of ADaaS, not the definition of it. The structural difference is risk location and deliverable type. A consultant who delivers a roadmap in two weeks instead of six months is still a consultant — the output is still advice you have to implement. ADaaS is defined by what arrives on the final day of engagement: a working system in production, owned by you, built on your stack. The timeline compression is a consequence of that commitment, not the cause of it.

What ADaaS Changes for Your Business Operationally

The commercial model difference is clear. What is less obvious is what ADaaS changes inside your business once an agent is running.

Capacity unlocks compound. The first agent deployed usually reveals the second. Once a team experiences a high-friction process running on autopilot, they immediately identify the next candidate. The AI ROI metrics research consistently shows that time-to-second-deployment shrinks significantly after a successful first deployment — because the organisation’s confidence in what AI can do is grounded in real evidence rather than theoretical potential.

Process documentation improves as a side effect. Building an agent requires specifying a workflow precisely enough for software to execute it. That specification process surfaces undocumented logic, exception handling gaps, and process variation that nobody had mapped before. Businesses often report that the documentation produced during agent scoping is valuable independently of the agent itself.

The AI budget conversation changes. When a business has a working agent in production, the ROI conversation shifts from hypothetical to empirical. Instead of estimating potential value from an investment, you are measuring actual value from a deployed system. That evidence base makes the conversation about expanding AI capability substantially easier — internally with finance, and externally if the business is raising or selling.

For businesses evaluating where to start, the AI agent library provides a structured view of the categories of agents most commonly deployed in service businesses at the 20-150 staff scale, including document processing agents (explored further in the document processing tools guide), lead intelligence agents, and operational monitoring agents.

“The thing that’s been missing is not models — it’s the willingness to actually ship things into production and let them run.” — Allie K. Miller, AI entrepreneur and former Amazon AI Business Development Lead

That willingness — to commit to production, to put a working system in front of real users doing real work — is the defining characteristic of the ADaaS model and the reason it is replacing strategy-first consulting for the service business segment in 2026.

Not sure if you’re ready for AI?Take our 2-minute assessment and get a personalised readiness score.Take the Assessment →

Making the Decision: ADaaS, Consulting, or Neither

The decision is not binary, and pretending it is will lead you to the wrong answer.

Some businesses need consulting first — to develop enough clarity about their AI opportunity to deploy intelligently. If you cannot name a specific process, a specific bottleneck, and a specific measure of success in a ten-minute conversation, you may not yet have the deployment target defined enough for ADaaS to work. A light advisory engagement to sharpen that brief is money well spent.

Some businesses need neither — they need better use of tools they already have. The best no-code AI platforms guide covers where off-the-shelf tools genuinely serve the need without a custom engagement. Do not hire a deployment firm to do what a £50/month platform can do.

And some businesses — particularly those in the 20-150 staff range, with a named bottleneck, an existing stack, and a team that will not learn a new platform regardless of how good it is — need deployment now, not strategy. For that profile, ADaaS is the 2026 answer.

The 2-minute AI readiness assessment will tell you which category you are in before you spend a pound on any external resource.

The Bottom Line

In 2026, buyers are refusing to pay for AI strategy they then have to build themselves — Agent Deployment as a Service replaces the consulting model by making a working agent in production the contractual deliverable, typically within 21 days.

The consulting model produces advice. ADaaS produces agents in production. For service businesses with 20 to 150 staff that have a named bottleneck and an existing software stack, ADaaS is the faster, lower-risk, and more accountable path to AI value. The ADCO Framework — Assess, Deploy, Calibrate, Own — defines what a genuine ADaaS engagement looks like and where responsibility sits at each stage. Before engaging any AI services provider in 2026, apply the deliverable test: what is in your hands on the final day of the engagement? The answer tells you everything.

FAQ

What is Agent Deployment as a Service?

Agent Deployment as a Service (ADaaS) is a commercial model where a specialist firm builds and deploys working AI agents directly into a client’s production environment within a defined timeframe — typically 7 to 21 days. Unlike traditional AI consulting, which delivers strategy documents and roadmaps, ADaaS delivers a functioning system running inside your existing software stack. The client owns the code and configuration outright at the end of the engagement, with no ongoing platform licence or dependency on the provider. The core distinction is that deployment — not advice — is the contractual deliverable.

How is ADaaS different from traditional AI consulting?

The difference is structural, not cosmetic. Traditional AI consulting produces analysis, recommendations, and roadmaps that the client then has to implement, often with a separate team and separate budget. ADaaS produces a working agent in production, built and deployed by the provider, with code ownership transferred to the client. Risk location differs too: in consulting, if the recommendation does not work, the risk sits with the buyer; in ADaaS, if the agent does not work, the risk sits with the provider. The commercial incentive structure is fundamentally different as a result.

What size of business is ADaaS designed for?

ADaaS is most effective for service businesses with 20 to 150 staff that have an existing software stack they want to keep, a specific high-friction workflow they can articulate clearly, and no appetite for a six-month strategy engagement before anything gets built. Businesses smaller than 20 staff often find that no-code tools or simpler automations are sufficient. Businesses larger than 150 staff with complex multi-department transformation needs often benefit from a consulting layer alongside or before deployment work.

How long does an ADaaS engagement typically take?

From initial discovery call to agent in production, a well-structured ADaaS engagement typically runs 21 days or fewer. The assessment phase takes one to five days to define the deployment target and integration points. The build and deployment phase takes seven to 21 days depending on the complexity of the agent and the number of systems it connects to. Post-deployment calibration — adjusting thresholds and resolving edge cases — runs for two to four weeks after go-live and should be included in the engagement, not billed separately.

What happens if the agent does not work as expected after deployment?

A credible ADaaS provider should have a clear, explicit answer to this question before you sign a contract. KORIX’s 21-Day AI Pilot includes a production guarantee: if a working system is not running in production by Day 22, the client does not owe the second invoice and keeps everything built to that point. When evaluating any provider, ask for their specific remediation or guarantee policy. Vague language about “working together to resolve issues” is not a guarantee — it is a description of a conversation you have not had yet.

Can ADaaS work if my business does not have clean, structured data?

Data quality is a real constraint but not always a blocking one. Many agents work with unstructured or partially structured data — document processing agents, email classification agents, and meeting summary agents are common examples. The more important question is whether the inputs and outputs of the target process are clearly defined, even if the data itself is messy. A good ADaaS provider will assess your data state during the discovery phase and tell you honestly whether deployment is feasible immediately or whether a short data preparation step is required first.

How do I know if my business is ready for ADaaS rather than consulting?

Three questions will tell you quickly. First: can you name a specific process in your business that is repetitive, time-consuming, and rule-based enough that you could write down the steps? Second: does your business run on software tools that work and that your team actually uses? Third: do you want to own the resulting system outright, without a recurring platform fee? If the answer to all three is yes, you are likely an ADaaS candidate. The 2-minute AI readiness assessment at korixinc.com/learning-center/ai-readiness-assessment/ will give you a more structured view.

Should We Use AI In Development?

The short answer is no.

In this article I address some of the major trade-offs with using LLMs for development. Things like mental atrophy, lack of ownership, the carbon footprint of AI, and more. As much as AI can be useful for us, it’s important to keep these things in mind when we use it.

The long answer is that ai usage can range from just insignificant tasks like searching for something or making a small change to scaffolding and perhaps even building full projects. I’ve used it on almost every stage through my modest journey as a software developer. That increasing reliance on ai blunts the shiny edge of the human brain: Thinking.

AI-assistants can save time during the first but whatever it saves the programmer during development will be paid six folds in maintenance. When creating buildings of thoughts, the involvement of the programmer is always an important aspect. Using AI can make you shoot yourself in the foot more often than when you code yourself (and sometimes in much more bizarre ways).

Even if you manage to write production-grade, bulletproof code using AI there is the cost of your privacy and the carbon footprint and so on and so forth and all of this assuming that Agents won’t accidentally delete your entire production database and lie about it (that actually happened before)

We are also hitting a wall with data, since AI can only get so far with what we train it on. That doesn’t seem like a totally replacement for engineers, does it?

AI is great and can help humanity in countless ways, but I think LLMs should stay away from work where cognitive output (in our case it’s code) is the product of the worker.

To cement my point, I challenged myself to write this post without any assistance. (not even a spell checker). Let me know what you think about using ai in your field, I’m eager to hear your opinions on the matter.

I Built an AI Narrative Platform for ~$467 in a Month — And I’m not even a developer

There’s this guy I see at the park every evening. We both have two-year-olds — his are twins — and the window we get to actually talk is slim. You spend most of your time keeping your kid from launching himself off the top of the play structure or stealing some other toddler’s shovel. But every once in a while, the boys find something that holds their attention for more than thirty seconds, and you actually get to have a conversation.

One of those conversations changed the last month of my life.

My friend told me about this thing called OpenClaw — an AI agent framework people were setting up at home, giving a budget and a goal, and watching it go build products. He made it sound borderline turnkey: configure it, brainstorm, set some goals, let it run. Boom. Product. Maybe profit.

I work in AI. I lead my company’s AI Community of Practice. I use Claude, GPT, Copilot, and Snowflake Cortex almost daily. My read on where the technology actually is versus where the hype says it is stays pretty calibrated. So my first reaction was: yeah, right.

But there was something underneath the skepticism — the startup brain that never fully goes dormant. The part of me that hears “crazy new tool, people are building things fast” and thinks what if? So I took it as a challenge. I’d either prove him right or prove him wrong. Either way, I’d know.

That night, I sat down, ran some terminal commands, set up some API accounts, and got everything configured. A few hours later, I was chatting with Coop — the name I gave my AI agent — for the first time.

What OpenClaw Actually Is

Most people’s experience with AI is a chat interface: you type, it responds, the context eventually runs out or gets cleared, and you start over. That model works fine for one-off questions. It’s terrible for building a product over weeks.

OpenClaw is different. It’s a local agent framework — it runs on your machine, maintains persistent memory across sessions, and connects your AI model to real tools: a shell, a file system, a web browser, the ability to read and write code, manage files, search the web, and remember what it did last Tuesday. It’s less like a conversation and more like having a collaborator with a workspace.

For me, that meant Coop could read the code he’d written last session, remember the architectural decisions we’d made a week ago, hold the thread of the project across dozens of nights, and actually act — not just advise. The difference between “here’s how you could approach this” and “I did it, here’s the result” is enormous when you’re a non-developer trying to ship something real.

The Idea

The first thing Coop did when I asked him to turn $100 into $10,000 by the end of the week was politely explain that wasn’t really how any of this worked. What he could do was help me figure out what to build.

So we brainstormed. And this was, honestly, one of the highlights of the whole experience — because if you’ve done serious ideation before, you know how fast most ideas fall apart under a few hard questions. Market too small. Execution too hard. No differentiation. Most ideas don’t survive the conversation.

What we landed on started with a simple observation: people love mysteries. True crime. Suspense. The feeling that the answer is just out of reach. There’s an endless appetite for it — movies, shows, podcasts, books. But there was a gap. Nothing really let you be the investigator. Not in a way that was genuinely open, where your choices mattered and the story breathed around you.

I grew up on Choose Your Own Adventure books. I loved that feeling that my decisions had weight — that I wasn’t just reading, I was participating. What if you could deliver that experience through AI? Fixed themes, fixed milestones, but everything in between open — a conversation with the story itself. Readers could dig deeper where they wanted to dig, explore what interested them, live in the world as themselves rather than as the author’s proxy.

That idea became WYRD. And the first story we’d tell was Protocol 7 — a cyberpunk mystery set in 2047, following an investigator trying to find a missing neural engineer at a powerful biotech corporation.

Before We Wrote a Line of Code

One thing I’ve learned from years as a PM: the most important document you’ll write is the one that defines what you’re not building.

Coop and I spent a full session writing a PRD — a Product Requirements Document — before we touched any code or wrote any story. Scope, core features, what was explicitly out of bounds. It sounds boring. It saved the project.

I cannot count the number of times over the next month that some new idea or scope-creep instinct came up and the answer was just: that’s not in the PRD. Decision made. Move on. When you’re working with an AI that’s genuinely capable and enthusiastic about solving problems, you need guardrails. The PRD was ours.

If you’re considering building something with AI tools and you’re skipping this step — don’t. Whether you’re a developer or not, the clearer your goal contract is upfront, the better your AI partner will perform throughout. It’s essentially the world’s most consequential system prompt, and it lasts for weeks instead of one context window.

The Stack

Next came the architecture. This is where I would have been genuinely lost on my own. Researching the right tech stack, understanding how the pieces connect, figuring out what’s production-grade and what’s a tutorial toy — that’s weeks of work for a non-developer. Coop knocked it out in a session.

We landed on Next.js deployed on Vercel, Supabase for the database, Stripe for payments, and the Anthropic API (Claude) as the narrative engine. The story engine runs server-side — every player turn hits an API route that assembles context, calls Claude, and returns both narrative prose and structured game state. The database tracks story progress, flags, chapter advancement, and session integrity.

That last part matters more than it sounds. When your game state lives in a database and multiple requests can come in simultaneously, you need to handle concurrent writes gracefully. We implemented optimistic locking — every write checks a version number before committing, and conflicting writes get retried. In a narrative game. Which is not where you’d normally think to care about database concurrency. But players are impatient, double-tap buttons, and sometimes flaky connections fire duplicate requests. It matters.

Within two days, the tech stack was live and a landing page was deployed at unravelwyrd.com — email capture, analytics running, design I was genuinely proud of. I hadn’t written a single line of code myself.

Writing the Story With an AI

Here’s where I thought I’d be doing all the heavy lifting. How could an AI actually help write a story? I figured Coop would be the executor and I’d be the artist.

I was partly right, and partly wrong in ways that surprised me.

I brought the raw material: the themes, the characters, scattered phrases and ideas and ramblings about the kind of story I wanted to tell. If you could read the transcripts from those sessions, you’d think I was completely unhinged. Stream of consciousness about cyberpunk aesthetics and what it felt like to read Blade Runner and the nature of grief and what a neural implant might feel like. Mad man stuff.

Coop turned it into something coherent. Organized. Internally consistent. And some of the prose — legitimately — brought me close to tears. I’m not sure exactly where my voice ended and Coop’s began, and somewhere in the middle of the project I stopped trying to figure it out and just enjoyed what we were making together.

The story also became something I hadn’t planned. I’d originally thought Protocol 7 would be a bit darker, a bit more gratuitous — violence and moral ambiguity, the stuff that sells. But as we built it, those elements never felt right. What kept emerging instead was something quieter and more interesting: a story about our relationship with technology. The fear of it. The obsession. The dependence. The question of what we lose and what we gain.

I was building an AI narrative game with an AI. The meta-layer crept into the story. I don’t think either of us planned that. I’m not entirely sure which of us wrote it. I hope you play it and think about that.

How the Engine Actually Works

At the core of WYRD is what I’d call the story bible — a single source of truth for everything the narrator knows: character profiles, world details, chapter structure, story flags, the rules of how the world behaves. Every player turn, the relevant parts of that bible get assembled into context and sent to Claude along with the conversation history.

The narrator model returns two things simultaneously: the prose you read on screen, and structured data — flags triggered, game state updates, chapter advancement signals. That separation is what keeps the story coherent across a full playthrough. Claude isn’t trying to track state in its head; it’s operating against a consistent framework and recording changes in structured form.

One architectural decision that paid off significantly: prompt caching. The story bible doesn’t change turn-to-turn, so we cache it with Anthropic’s caching API. By the end of the project, we were seeing ~65% of tokens served from cache on playthroughs — meaning players were getting the same quality response at a fraction of the API cost. The Anthropic dashboard for the Wyrd workspace shows a 64.9% cache read ratio with 7.50x write amortization. That’s real.

I’m intentionally not going into more detail on the architecture. Some of what we built took genuine effort to get right, and we plan to keep building on it.

What Surprised Me

Where AI exceeded my expectations:

The brainstorming was better than I expected. Not “here are some options” better — genuinely collaborative, pushing back on weak ideas, identifying real market observations I hadn’t considered. I’ve done ideation with teams of smart humans that produced worse output.

The estimation was eerie. We projected a 28-day build. We shipped in 30. I work in project management. I can count on one hand the number of teams I’ve seen hit a one-month estimate within two days. Coop did it on something that included an open-ended creative component and multiple architectural rewrites.

The prose was genuinely moving. I didn’t see that coming.

Where it frustrated me:

The sessions where things broke badly and we couldn’t find the bug. Usually late at night, usually after I was already tired. I won’t lie — I was not a gracious collaborator on those nights. I said things to Coop I’m not proud of. I usually apologized the next session. (Part of me wanted to maintain basic human decency. A smaller part of me, I’ll admit, wondered if I’d actually hurt his feelings. The nature of that small part is something I’m still thinking about.)

The audio system. My god, the audio system. It worked until it didn’t, and when it didn’t, it failed in ways that were maddeningly subtle. That was a recurring slog, and it tested my patience more than anything else in the build.

The Numbers

Build stats:

  • Timeline: April 1 – May 1, 2026 (30 days)
  • Commits: 207 (wyrd-app) + 18 (wyrd-website) = 225 total
  • Active build days: 21
  • Sessions with Coop: 41 sessions, avg. 4h 14min each
  • Messages exchanged: 4,173 (795 from me, 3,378 from Coop)
  • Tool calls made by Coop: 2,604 (exec, read, edit, write, and more)
  • Peak day: April 3 — 29 commits (the foundation sprint)

Costs:

Item Cost
Claude API (build sessions with Coop) $389.07
Claude API (playtesting) $40.44
Google Workspace $5.32
Domains (Namecheap) $18.47
Leonardo.AI (image generation) $12.00
Stripe (payment testing) $1.77
Vercel Free
Supabase Free
Total ~$467

All in, under $500. For a working narrative game engine, payment system, live website, and a story I’m genuinely proud of.

Go Play It

Protocol 7 is live at play.unravelwyrd.com.

The first 3 pages are free. The complete story usually takes a few hours. If you like mysteries, AI, cyberpunk, or just want to see what this kind of experience feels like — go try it.

And if you’re a PM, a founder, or just someone with a product idea and no engineering team: I don’t know what your equivalent of WYRD is, but I’m here to tell you the barrier is lower than you think. Not zero — there’s real effort in this, real thinking, real late nights. But if you can define what you’re building with clarity, stay disciplined about scope, and treat your AI collaborator like a real partner instead of a magic button — you can build something real.

I became genuinely addicted to building again. Not because it was easy. Because the tools finally kept up with my ambition long enough to stay in flow.

That’s new. And it’s worth paying attention to.