面向 Spec 与 Architecture 的 AI 编程：从写代码到写规格
面向 Spec 与 Architecture 的 AI 编程：从写代码到写规格
看完你会发现，你对「AI编程」的理解可能要更新了。
用 Claude Code 写了半年代码后，一个变化悄然发生：我花在写 CLAUDE.md、设计类型注解、画架构图上的时间，开始超过写业务代码的时间。
不是因为我变懒了，是因为 AI 生成代码的质量，越来越取决于你给它的规格有多清晰。
这正在成为一个系统性趋势。AI 编程的主流形态正在从「prompt → 代码」迁移到「spec → architecture → 代码」。规格文件取代提示词，成为 AI 编程的核心产物。
本文提纲
- 为什么「prompt → 代码」不够了
- Spec 层：CLAUDE.md / AGENTS.md / 类型注解
- Architecture 层：从规格到系统设计
- Context Engineering：规格的艺术
- 实战工作流：Spec → Architecture → Implementation → Review
- 五个正在成型的工具范式
- 你现在应该做什么
为什么「prompt → 代码」不够了
「prompt → 代码」是 AI 编程的 1.0 形态：你说一句话，AI 给你一段代码。这在写单个函数、生成组件、补全逻辑时很好用。但它有三个结构性瓶颈。
瓶颈一：上下文窗口有限，复杂系统装不下。 一个真实项目有几十个模块、上百个依赖、数千个文件。你不可能在 prompt 里描述整个系统。Claude Code 的解决方案是 CLAUDE.md——一个项目级的规格文件，Agent 每次启动时自动读取。但很多人还是把 CLAUDE.md 当注释写，没有把它当作「规格」来设计。
瓶颈二：AI 生成的代码缺乏架构一致性。 你让 AI 写一个 API 端点，它能写出能跑的代码。但这个端点的错误处理风格和项目其他端点一致吗？日志格式对吗？认证逻辑和现有中间件兼容吗？如果规格里没写，AI 就按自己的默认风格来——结果就是一个项目里混着五种错误处理模式。
瓶颈三：审查成本随代码量线性增长。 AI 一分钟能生成 200 行代码，你审 200 行代码需要五分钟。当代码量从 200 行变成 2000 行，审查就变成了瓶颈。解决方法不是让你审查得更快，而是让 AI 生成的代码从设计上就更可审查——这就是规格的价值：规格定义了契约，审查变成对契约的验证，而不是逐行读代码。
Spec 层：CLAUDE.md / AGENTS.md / 类型注解
Spec 层是 AI 编程的 2.0 形态。不是告诉 AI「写什么代码」，而是告诉 AI「这个项目的规则是什么」。
CLAUDE.md：项目级规格
CLAUDE.md 是 Claude Code 的项目上下文文件。Agent 每次启动时自动加载，不需要在 prompt 里重复。一个好的 CLAUDE.md 应该包含：
# Project: E-commerce API
## Architecture
- Monorepo: frontend/ (Next.js) + backend/ (Go) + shared/ (protobuf)
- API style: RESTful, OpenAPI 3.0 spec in docs/openapi.yaml
- Auth: JWT with RS256, refresh token rotation
- Database: PostgreSQL with sqlc (no ORM, generated code)
## Conventions
- Error handling: return (response, error) tuples, wrap with fmt.Errorf
- Logging: structured JSON via slog, never fmt.Println
- Testing: table-driven tests, coverage > 80%
- Naming: exported types PascalCase, unexported camelCase
## Agent Instructions
- Always check docs/openapi.yaml before adding endpoints
- Run `make generate` after modifying protobuf definitions
- Never bypass sqlc — if you need raw SQL, add it to sqlc.yaml
- Run `golangci-lint run` before considering a task complete关键区别：这不是文档，是规格。它定义了 AI 必须遵守的约束——架构决策、编码规范、工具链规则。AI 违反这些约束就是 bug，不是风格选择。
AGENTS.md：仓库级协议
AGENTS.md 是更通用的仓库协议格式，被越来越多的 AI 工具支持（Claude Code、Codex、Cursor、NOOA）。它定义的不只是单个项目的规则，还有跨仓库的约定：
# Agent Conventions
## Testing
- Every PR must pass: `pytest -x --cov=src --cov-fail-under=80`
- Integration tests require Docker; mark with @pytest.mark.integration
## Dependencies
- Add new deps via `uv add`, never edit pyproject.toml manually
- Security scan: `pip-audit` must pass before merge
## Agent Skills
- Skills live in skills/ directory, each with SKILL.md
- Load skills progressively: only when the task matches类型注解：机器可读的契约
类型注解是最被低估的规格形式。NVIDIA NOOA 的核心设计就是：类型注解就是接口契约。
class OrderService(Agent):
async def create_order(
self, user_id: UserID, items: list[OrderItem]
) -> OrderResult:
"""Create an order from cart items.
Returns OrderResult with order_id on success,
or InsufficientStockError if any item is unavailable.
"""
...... 方法体告诉运行时：这个方法由 LLM 实现。但类型签名——UserID、list[OrderItem]、OrderResult——是硬约束。AI 生成的代码必须匹配这些类型，否则运行时报错。这比写一段自然语言的 prompt 描述接口要精确得多。
Spec 层的三种形式——CLAUDE.md（项目规则）、AGENTS.md（仓库协议）、类型注解（接口契约）——构成了 AI 编程的规格基础设施。
Architecture 层：从规格到系统设计
规格定义了「规则」，架构定义了「结构」。当 AI 需要实现一个复杂功能时，你不应该让它直接写代码——你应该先让它理解架构。
架构图作为 AI 输入
Diagram Design（23K Stars）的 38 种图表类型在这里有了新用途：不只是给人看的文档，是给 AI 看的架构规格。
你: "根据这个架构图，实现订单服务的微服务拆分"
[附上 architecture.html — 一个 5 服务的 C4 架构图]
Agent: -> 读取架构图，理解服务边界
-> 为每个服务生成 API 定义
-> 实现 gRPC 通信层
-> 生成 Docker Compose 配置
-> 写集成测试验证服务间通信当你把架构图作为输入给 AI，它不再是「写一个函数」，而是「实现一个系统设计」。输出的一致性大幅提升，因为架构约束了所有后续决策。
分层实现：不要让 AI 一次做完
工业化的核心原则是分工。AI 编程也应该分层：
graph TB
A["Spec Layer
CLAUDE.md + AGENTS.md + Type Annotations"] --> B["Architecture Layer
Diagrams + API specs + Module boundaries"]
B --> C["Interface Layer
OpenAPI / protobuf / GraphQL schemas"]
C --> D["Implementation Layer
AI generates code per interface"]
D --> E["Review Layer
Tests + Lint + Agent Eval"]
style A fill:#FF6B6B,color:#000000
style B fill:#4ECDC4,color:#000000
style C fill:#45B7D1,color:#000000
style D fill:#96CEB4,color:#000000
style E fill:#FFEAA7,color:#000000每一层有明确的输入和输出：
- Spec → 规则和约束
- Architecture → 系统结构和边界
- Interface → 机器可读的契约（OpenAPI、protobuf）
- Implementation → AI 按契约生成代码
- Review → 自动化质量验证
这个分层模型的好处：每一层的输出是下一层的输入，任何一层出问题都只影响下游，不会污染整个链路。
Context Engineering：规格的艺术
Anthropic 在 Engineering 博客里反复强调的一个概念：Context Engineering 比 Prompt Engineering 更重要。
Prompt Engineering 是「怎么说让 AI 理解你的意图」。Context Engineering 是「怎么组织信息让 AI 在正确的时间获得正确的上下文」。
Spec-driven AI 编程本质上是 Context Engineering 的实践。好的规格不是把所有信息一次性塞给 AI，而是渐进式披露（progressive disclosure）：
- CLAUDE.md 提供项目级常驻上下文——每次都在
- AGENTS.md 提供仓库级协议——跨项目复用
- 类型注解提供方法级契约——编译时检查
- Architecture 文档提供任务级上下文——按需加载
- Skill 文件提供领域知识——匹配时激活
NOOA 的 SKILL.md 系统就是这个模式的实践：13 个内置 Skills 不是全部加载，而是「progressive disclosure——SKILL.md 先路由行为，再路由布局。类型、动画参考只在相关时加载」。
Diagram Design 也一样：38 个类型参考文件，只有被选中时才加载。不是把 38 种图表的规则全部灌给 AI，是让它先选择类型，再加载对应规格。
实战工作流：Spec → Architecture → Implementation → Review
一个完整的 spec-driven AI 编程工作流长这样：
第一步：写 Spec（10 分钟）
在 CLAUDE.md 里新增一段：
## Feature: Order Tracking
- New service: tracking/ (Go package)
- API: GET /orders/{id}/tracking returns tracking events
- Events sourced from carrier webhook (POST /webhooks/carrier)
- Cache: Redis, TTL 5 min, key: tracking:{order_id}
- Fallback: if cache miss and carrier timeout, return last known event10 行规格定义了功能边界、API 契约、缓存策略和降级逻辑。
第二步：让 AI 设计 Architecture（5 分钟）
你: "根据 CLAUDE.md 里的 Order Tracking spec，
画一个架构图，展示 tracking 服务的组件和数据流"
Agent: -> 生成 architecture.html (Diagram Design)
-> 展示: Webhook handler -> Event store -> Cache -> API第三步：让 AI 实现 Interface（3 分钟）
你: "根据架构图，生成 OpenAPI spec 和 protobuf 定义"
Agent: -> 生成 openapi.yaml (tracking endpoint)
-> 生成 tracking.proto (gRPC service)
-> 运行 make generate 生成 Go stubs第四步：让 AI 实现（10 分钟）
你: "根据 interface spec 和 CLAUDE.md 规范，
实现 tracking 服务"
Agent: -> 实现 webhook handler
-> 实现 event store (PostgreSQL)
-> 实现 cache layer (Redis)
-> 实现 API endpoint
-> 写 table-driven tests
-> 运行 golangci-lint第五步：Review（5 分钟）
你: "审查这个 PR：spec 是否被正确实现？
测试覆盖率？有没有违反 CLAUDE.md 的规范？"
Agent: -> 对照 spec 逐项验证
-> 运行测试 + lint
-> 输出审查报告总计 33 分钟，产出：规格文档 + 架构图 + API 定义 + 完整实现 + 测试 + 审查报告。传统方式这个工作量至少 2-3 小时。
五个正在成型的工具范式
范式一：项目规格文件（CLAUDE.md / AGENTS.md）。 从可选的注释变成必选的规格。未来每个项目根目录都有一个 spec 文件，就像每个项目都有 README 一样。
范式二：架构图作为 AI 输入（Diagram Design）。 从「给人看的文档」变成「给 AI 看的规格」。38 种编辑级图表类型，每一种都是一种架构语言的语法。
范式三：类型注解作为接口契约（NOOA）。 Python 类型注解从「可选的文档」变成「强制的契约」。... 方法体是「AI 实现」的信号，类型签名是「AI 必须遵守」的约束。
范式四：Skill 作为领域知识包。 SKILL.md 格式成为跨平台标准（Claude Code / Codex / Pi / NOOA）。Skill 不是文档，是可被 Agent 自动加载和使用的知识包——在正确的时间提供正确的上下文。
范式五：Agent Eval 作为质量门禁（HarnessEval-W）。 评测本身变成 Agent 任务——不是跑个 lint 就完事，是让 Agent 推理「这个实现是否满足规格」。证据树（evidence tree）让每次评测都可审计。
你现在应该做什么
第一，把 CLAUDE.md 当规格写，不是当注释写。 定义架构决策、编码规范、工具链规则。AI 违反这些规则就是 bug。每加一个功能，先更新 spec。
第二，先画架构图再让 AI 写代码。 用 Diagram Design 或任何工具，先确定系统结构和数据流。架构图是给 AI 的最高层规格。
第三，用类型注解定义接口契约。 不管你用什么语言，类型注解是最精确的规格形式。AI 生成的代码必须匹配类型，这是编译时/运行时的硬约束。
第四，分层实现，不要让 AI 一次做完。 Spec → Architecture → Interface → Implementation → Review。每一层有明确的输入输出，出问题只影响下游。
第五，建一个 Skill 库。 把团队的最佳实践、设计模式、领域知识编码成 SKILL.md 文件。Agent 按需加载，不需要在每次 prompt 里重复。
工业化的逻辑在这里同样适用：规格取代手艺成为核心产物。 程序员的价值不在于写代码，在于定义规格和审查实现。CLAUDE.md 就是你的蓝图，类型注解就是你的施工标准，架构图就是你的工程图纸。AI 是你的施工队，但施工队只按图纸干活。
参考文档与链接
- Anthropic: Maximizing the value of your Claude Code sessions - 官方 CLAUDE.md 最佳实践
- Anthropic Engineering: Effective context engineering for AI agents - Context Engineering 方法论
- Anthropic Engineering: Effective harnesses for long-running agents - Harness 设计与渐进式加载
- Diagram Design: 38 editorial diagram types - 架构图作为 AI 输入
- NVIDIA NOOA: Object-Oriented Agents - 类型注解作为接口契约
- HarnessEval-W: Agentifying evaluation - 评测作为质量门禁
- Cursor Blog: Towards self-driving codebases - 自驱代码库愿景
你用 CLAUDE.md 吗？写的什么内容？评论区聊聊你的 spec 实践。觉得有用点个赞让更多人看到。
作者: itech001 来源: 公众号：AI人工智能时代 网站: https://www.theaiera.cn/ 每日分享最前沿的AI新闻资讯和技术研究。
本文首发于 AI人工智能时代，转载请注明出处。
