Spec Kit + Codex：复杂企业项目如何循序渐进推进

JaxToken原创2026/7/28大约 10 分钟

Spec Kit + Codex：复杂企业项目如何循序渐进推进

在简单项目中，Spec Kit + Codex 很容易使用：

需求
  ↓
Spec
  ↓
Plan
  ↓
Tasks
  ↓
Codex 实现

但一旦进入真实企业项目，问题就完全不同了。

典型企业系统可能包含十几个甚至几十个模块：

user
product
order
inventory
payment
promotion
coupon
delivery
invoice
notification
risk
settlement
...

这些模块之间还存在复杂的同步调用、异步事件、数据库事务和业务依赖。

这种情况下，如果直接让 Codex：

分析整个系统，然后完成 XXX 功能

很容易遇到：

上下文过大
模块边界模糊
AI 错误理解依赖关系
修改范围失控
架构逐渐退化
Spec 越来越庞大
Task 数量快速膨胀

因此，大型企业项目使用 Spec Kit + Codex 的核心，不是让 AI 一次理解整个系统，而是：

通过架构边界不断缩小 AI 的决策空间。

推荐采用：

系统级约束
    ↓
模块级上下文
    ↓
Feature 级规格
    ↓
Task 级执行

也就是一种分层的 Spec Driven Development。

一、建立三层规格体系

复杂项目不应该只有一个巨大的 Spec。

更合理的方式是建立三层结构：

项目
├── 系统级
│   ├── Constitution
│   ├── Architecture
│   ├── Module Map
│   └── Dependency Rules
│
├── 模块级
│   ├── order
│   ├── payment
│   ├── inventory
│   └── user
│
└── Feature级
    ├── 创建订单
    ├── 支付订单
    ├── 取消订单
    └── 修改地址

三层承担不同职责。

系统级

回答：

整个系统遵守什么规则？

例如：

架构风格
模块边界
技术栈
分层原则
测试要求
安全要求
数据一致性原则

这类规则应该相对稳定。

模块级

回答：

这个模块负责什么？

例如 order：

职责：
订单生命周期管理

核心模型：
Order
OrderItem

提供能力：
CreateOrder
CancelOrder
QueryOrder

依赖：
product
inventory
promotion

禁止依赖：
payment
delivery
invoice

模块规格的核心作用是形成清晰的 Bounded Context。

Feature 级

回答：

这一次具体改变什么？

例如：

取消订单
支付订单
修改订单地址
锁定库存
退款

Feature 才是 Spec Kit 最适合处理的执行单位。

二、第一阶段：先理解系统，不要急着写代码

对于存量企业系统，我不建议第一步就运行：

$speckit-specify

然后开始开发。

应该先建立整个系统的地图。

至少整理四类信息：

模块清单
模块职责
模块依赖
关键业务链路

例如一个电商系统：

           product
              │
              ↓
user ─────→ order
             │ │
       ┌─────┘ └─────┐
       ↓             ↓
   inventory       promotion
       │             │
       └─────┬───────┘
             ↓
           payment
             │
       ┌─────┴─────┐
       ↓           ↓
    invoice     delivery
       │
       ↓
   settlement

这张图非常重要。

因为 Codex 如果不知道模块关系，很容易从代码引用关系反向猜测架构。

而：

代码依赖关系不一定等于正确的业务依赖关系。

很多老系统本身就存在不合理依赖。

因此不能简单让 AI：

扫描代码，自动理解系统架构

更可靠的方法是人工明确系统边界，再让 AI 在边界内工作。

三、建立系统级 Architecture Context

建议在项目根目录维护：

docs/
├── architecture.md
├── module-map.md
├── dependency-rules.md
└── domain-glossary.md

architecture.md

描述整体架构：

架构风格：
Modular Monolith

分层：

interfaces
application
domain
infrastructure

模块之间禁止直接访问对方数据库。

跨模块交互通过：

Application API
Domain Event
Integration Event

module-map.md

描述所有模块：

order

职责：
订单生命周期管理

提供：
OrderQueryService
OrderCommandService

依赖：
product
inventory
promotion

禁止依赖：
payment
delivery
invoice

这样 Codex 不需要每次重新分析整个代码库。

dependency-rules.md

显式定义模块依赖：

允许：

order → product
order → inventory
order → promotion

payment → order

delivery → order

禁止：

order → payment
inventory → order
domain → infrastructure

把架构意图显式化非常重要。

domain-glossary.md

维护统一领域语言：

Order
订单

OrderItem
订单项

Inventory Reservation
库存预占

Payment
支付

Settlement
结算

对于 AI 开发尤其重要。

否则不同 Feature 中可能出现：

Customer
User
Buyer
Member

实际上描述的是同一个业务概念。

四、第二阶段：先治理模块依赖

大型系统最严重的问题通常不是代码量，而是：

模块之间的边界失控。

例如：

OrderService
    ↓
PaymentService
    ↓
OrderService

形成循环依赖。

或者：

Order
 ↓
Inventory
 ↓
Promotion
 ↓
Order

甚至出现：

order
直接查询
payment 数据库

这类架构对于 AI Agent 非常危险。

因为 Codex 会根据现有代码学习模式。

如果系统本身存在大量错误依赖，AI 很可能继续复制这种模式。

所以最好把架构规则变成自动化约束。

例如 Java 项目可以使用 ArchUnit。

概念上：

layeredArchitecture()
    .consideringOnlyDependenciesInLayers()
    .layer("Domain")
    .definedBy("..domain..")
    .layer("Application")
    .definedBy("..application..")
    .layer("Infrastructure")
    .definedBy("..infrastructure..");

这样形成：

Constitution
      ↓
Architecture Rules
      ↓
ArchUnit
      ↓
CI

即：

Constitution 是软约束，Architecture Test 是硬约束。

五、第三阶段：逐个模块建立上下文

系统级架构确定后，不要立即让 Codex开发复杂 Feature。

先逐模块建立 Context。

例如：

modules/
└── order/
    ├── AGENTS.md
    ├── domain.md
    ├── api.md
    └── dependencies.md

domain.md

描述领域模型：

Order Context

Aggregate：

Order

Entity：

OrderItem

Value Object：

OrderId
Money
Address

状态：

CREATED
PAID
SHIPPED
COMPLETED
CANCELLED

api.md

描述模块能力：

Command：

CreateOrder
CancelOrder
ConfirmOrder

Query：

GetOrder
ListOrders

dependencies.md

描述模块依赖：

Inbound：

Payment
Delivery

Outbound：

Inventory
Product
Promotion

这样 Codex 在修改 Order 模块时，只需要理解：

系统规则
+
Order Context
+
当前 Feature

而不需要每次理解完整系统。

六、按照依赖拓扑逐步推进

模块治理顺序也很重要。

不要按照：

user
product
order
payment
...

这种代码目录顺序。

而应该按照依赖关系推进。

例如：

product
   ↓
inventory
   ↓
order
   ↓
payment
   ↓
delivery

可以分批：

第一批：

user
product

第二批：

inventory
promotion

第三批：

order

第四批：

payment

第五批：

delivery
invoice

第六批：

settlement

原则是：

优先治理依赖较少、边界更稳定的模块。

然后逐步向核心交易链路推进。

这样每治理一个模块，就会为后面的模块降低复杂度。

七、Feature 才是 Spec Kit 的核心执行单位

到了真正开发阶段，不应该为整个模块生成一个超级 Spec。

例如不要：

$speckit-specify

重新设计订单系统。

而应该：

specs/
└── order/
    ├── 001-create-order/
    ├── 002-cancel-order/
    ├── 003-change-address/
    └── 004-confirm-order/

例如开发「取消订单」：

$speckit-specify

订单取消功能。

用户可以取消未支付订单。

已经支付的订单不能直接取消，
必须进入退款流程。

已经发货的订单不能取消。

订单取消后：

- 释放库存
- 释放优惠券
- 记录订单操作日志

然后按照标准流程：

Specify
   ↓
Clarify
   ↓
Plan
   ↓
Tasks
   ↓
Analyze
   ↓
Implement

每一个 Spec 都保持足够小。

这对于 Codex 至关重要。

八、复杂跨模块业务单独建模

企业系统真正复杂的部分通常不是 CRUD。

而是跨模块业务流程。

例如：

创建订单
    ↓
查询商品
    ↓
计算优惠
    ↓
锁定库存
    ↓
创建订单
    ↓
支付
    ↓
生成配送单
    ↓
开票

这种 Feature 不应该简单塞进 order 模块。

建议建立：

business-flows/
└── checkout/
    ├── flow.md
    ├── sequence.md
    ├── consistency.md
    └── failure-scenarios.md

flow.md

描述业务流程：

CreateOrder
    │
    ├── Product
    │      查询商品
    │
    ├── Promotion
    │      计算优惠
    │
    ├── Inventory
    │      锁定库存
    │
    └── Order
           创建订单

sequence.md

描述调用关系：

Client
  ↓
Order Application
  ↓
Product
  ↓
Promotion
  ↓
Inventory
  ↓
Order Domain

consistency.md

明确：

哪些操作在本地事务中完成？

哪些通过最终一致性完成？

哪些使用事件？

哪些需要 Outbox？

哪些需要 Saga？

failure-scenarios.md

重点设计失败场景：

优惠计算成功
库存锁定失败

怎么办？

或者：

订单创建成功
支付失败

怎么办？

以及：

消息重复消费怎么办？

库存释放失败怎么办？

订单取消事件丢失怎么办？

这些实际上比正常流程更值得进行 Spec Driven Design。

九、推荐采用四阶段推进法

对于一个已有十几个模块的复杂项目，可以分成四个阶段。

Phase 1：Understand

目标：

建立系统地图。

完成：

模块清单
模块职责
模块关系
核心领域模型
关键业务流程
领域词汇表

这个阶段尽量不修改业务代码。

Phase 2：Guard

目标：

给 AI 建立护栏。

建立：

Constitution
AGENTS.md
Dependency Rules
Architecture Tests
Test Strategy
CI Quality Gate

形成：

规则
 ↓
自动验证
 ↓
AI 无法轻易突破架构边界

Phase 3：Standardize

目标：

让每个模块可以独立理解。

逐模块补齐：

模块职责
Domain Model
API
Dependencies
Database Ownership
Events

最终达到：

一个开发人员
或者一个 Codex Agent

只阅读一个模块的上下文
就能理解这个模块。

Phase 4：Develop

此后所有新增需求都按照：

Feature
   ↓
Spec
   ↓
Clarify
   ↓
Plan
   ↓
Tasks
   ↓
Codex
   ↓
Test
   ↓
Review

进行开发。

此时 AI 才真正进入日常研发流程。

十、推荐的项目目录

对于十几个模块的 Java 企业项目，可以采用：

root
├── AGENTS.md
│
├── .specify/
│   └── memory/
│       └── constitution.md
│
├── docs/
│   ├── architecture.md
│   ├── module-map.md
│   ├── dependency-rules.md
│   └── domain-glossary.md
│
├── business-flows/
│   ├── checkout/
│   ├── refund/
│   └── fulfillment/
│
├── specs/
│   ├── order/
│   ├── payment/
│   ├── inventory/
│   └── checkout/
│
├── modules/
│   ├── user/
│   │   └── AGENTS.md
│   │
│   ├── product/
│   │   └── AGENTS.md
│   │
│   ├── order/
│   │   └── AGENTS.md
│   │
│   └── payment/
│       └── AGENTS.md
│
└── pom.xml

Codex 的上下文因此形成逐级收缩：

Root AGENTS.md
        ↓
Constitution
        ↓
Architecture
        ↓
Module AGENTS.md
        ↓
Feature Spec
        ↓
Current Tasks

上下文越来越小。

约束越来越具体。

十一、Codex 不需要理解整个系统

大型项目使用 AI Agent 时，一个很容易出现的误区是：

AI 必须理解整个代码库才能正确开发。

实际上恰恰相反。

一个成熟的软件架构，本身就应该让开发者：

不需要理解整个系统
也能安全修改局部功能

AI 也是一样。

理想状态是：

全局上下文
     │
     ↓
Architecture Context
     │
     ↓
Bounded Context
     │
     ↓
Feature Context
     │
     ↓
Task Context

最终 Codex 在执行某个任务时，只需要知道：

我现在改什么

我可以调用谁

谁可以调用我

哪些东西禁止修改

什么条件算完成

这实际上与 DDD 的思想高度一致。

DDD 通过：

Bounded Context

控制业务复杂度。

而 Spec Driven Development 可以通过：

Context Boundary

控制 AI 的认知复杂度。

十二、从 AI Coding 到 AI Software Engineering

直接使用 Codex：

Prompt
   ↓
Code

本质仍然属于 AI Coding。

而加入 Spec Kit、DDD 和架构约束后：

Business Requirement
        ↓
Domain Model
        ↓
Architecture
        ↓
Specification
        ↓
Plan
        ↓
Tasks
        ↓
Codex
        ↓
Tests
        ↓
Architecture Validation
        ↓
CI

这时候开始从：

AI 写代码

升级成：

AI 参与软件工程

两者最大的区别不是代码生成能力，而是：

是否建立了可控的软件决策过程。

十三、最终推荐组合

对于中大型 Java 企业系统，我比较推荐：

DDD
+
Modular Monolith
+
Spec Kit
+
Codex
+
AGENTS.md
+
Architecture Tests
+
Automated Tests
+
CI Quality Gate

可以简单概括为四层：

DDD
负责业务边界

Architecture
负责技术边界

Spec Kit
负责需求和设计边界

Codex
负责实现

最终形成：

          Human
            │
            ↓
    Business / Architecture
            │
            ↓
        Spec Kit
            │
     Spec / Plan / Tasks
            │
            ↓
          Codex
            │
      Code / Test / Fix
            │
            ↓
 Architecture Test + CI

人的主要职责逐渐从：

写代码

转变为：

定义问题
确定边界
设计规则
做关键决策

而 AI 主要负责：

实现
测试
验证
重复性工程工作

总结

复杂企业项目引入 Spec Kit + Codex，最忌讳的方式是：

把整个代码库交给 AI
让 AI 自己分析
然后直接修改

更好的方式是：

系统级
    ↓
Architecture

模块级
    ↓
Bounded Context

Feature级
    ↓
Specification

Task级
    ↓
Codex

核心原则只有一句：

不要试图让 AI 一次理解整个系统，而要通过良好的架构，让 AI 每次只需要理解一个足够小的系统切片。

这可能也是未来 AI 软件工程与传统软件工程真正结合的关键。

优秀的软件架构过去解决的是：

如何让人类控制复杂度

未来同样需要解决：

如何让 AI 控制复杂度

从这个角度看，DDD、模块化、架构边界和 Spec Driven Development 并没有因为 AI 出现而过时。

恰恰相反：

AI 越强，边界越重要。