从 Human-native 到 Agent-native：我对 AI-native 软件工程的理解

AI-native 不是多用 AI，也不是把 Cursor、Copilot、Codex、ChatGPT 都接进开发流程就算完成升级。真正的 AI-native，是软件工程组织方式的变化。

很多团队现在停留在 AI-assisted：让模型补代码、写测试、解释报错、生成脚手架。效率确实提高了，但项目本身还是旧项目：隐式架构、散落上下文、靠人脑记忆维持一致性、靠资深维护者做最后校验。AI 只是被塞进一个 human-native 的工程环境里，像一个临时实习生，靠问答和猜测工作。

Agent-native 要求更高。它不是问“AI 能不能写这段代码”，而是问：这个项目是否天然适合 Agent 理解、修改、验证和持续演化？如果答案是否定的，那么问题不只在 AI，也在工程本身。

我把这套理解称为 Sealessland AI-native Principles。它的核心判断很简单：AI-native 软件工程的关键，不是让 AI 更自由，而是让 AI 在清晰架构、显式上下文、原子结构、最小权限、自动验证和 hook 护栏中高效行动。

Human-native 项目的根本问题

传统项目大多是 human-native 的。它们默认维护者拥有长期记忆，知道哪些模块不能动，知道某个函数为什么长成这样，知道 README 里没写的部署细节，知道一个字段虽然看似无用但线上依赖它。

这种项目对人类维护者并不一定友好，但人类可以用长期经验补洞。我们能通过历史记忆、口头约定、代码评审里的旧讨论、跨文件脑补能力，把不完整的上下文拼起来。

Agent 没有这种稳定记忆。它面对的是一次任务窗口、一段 prompt、一批文件和有限 token。项目越依赖隐式经验，Agent 越容易迷路。它可能读了很多文件，消耗大量上下文，最后仍然不知道真正的边界在哪里：这个 schema 是否是外部契约？这个测试是规范还是历史残留？这个目录是新架构还是旧架构？这个 helper 能不能复用？

所以我越来越相信一句话：如果 AI 都看不懂一个项目架构，那这个项目本身的工程可理解性就有问题。

这不是说项目要为了 AI 牺牲设计质量。恰恰相反，Agent-native 会逼迫我们把很多过去靠人脑维持的工程秩序显式化。它会放大坏架构，也会奖励好架构。

Agent-native 的核心定义

Agent-native 项目，是把代码从 human-readable modules 升级为 agent-executable units。

Human-readable module 的目标是让人能读懂；agent-executable unit 的目标是让 Agent 能在局部上下文内完成正确修改，并通过局部验证证明修改没有破坏契约。

这类项目追求四件事：

• 上下文局部性：正确修改所需的信息尽量靠近代码。
• 局部修改：任务能落在清晰边界内，而不是牵动全局脑补。
• 局部验证：模块有自己的 contract、schema、mock、golden case 和 regression test。
• 可审计演化：每次变更都能说明改了什么、为什么改、如何验证、剩余风险在哪里。

Agent-native 不是把项目拆得更碎，而是把项目组织成 context-complete unit：上下文局部完备单元。单元内部包含实现，也包含约束、行为样例、边界条件和 Agent 需要知道的维护注意事项。

Sealessland AI-native Principles

1. 架构白盒化

一句话定义：架构白盒化，就是让模块职责、依赖方向、数据流、状态边界、扩展点和不变量显式可见。

它解决的问题是“Agent 不知道哪里能改、哪里不能改”。很多项目的架构只存在于资深工程师脑子里，目录结构看似清楚，真实依赖却绕来绕去。Agent 在这种项目里很容易做出局部看似合理、全局破坏边界的修改。

工程例子：一个支付系统里，checkout 可以依赖 pricing 和 inventory，但不能反向依赖；payment_provider 是可替换扩展点；订单状态只能通过 state machine 迁移。这些不应该只藏在代码里，而应该写进 docs/architecture.md、模块 README、ADR，必要时用 lint 或 architecture test 固化。

可记住的总结：白盒化不是暴露一切，而是把正确修改必须知道的边界照亮。

2. 项目结构 Agent-native

一句话定义：Agent-native 项目结构，是把功能组织成上下文局部完备单元。

它解决的问题是“Agent 为了改一行代码，需要读半个仓库”。传统目录常按技术层拆分：controllers/、services/、models/、utils/。人类熟悉业务后能跨目录拼出完整功能，但 Agent 每次都要重新搜索。

工程例子：把 checkout 组织成一个 feature unit：contract.md 说明输入输出和业务不变量，schema.ts 定义结构，implementation.ts 放核心实现，implementation.test.ts 覆盖单元行为，regression.test.ts 固化历史问题，behavior.golden.md 记录典型行为，mock-data.ts 提供稳定样例，agent-notes.md 写维护注意事项。

可记住的总结：核心目标不是拆得更细，而是让正确修改所需的上下文天然最小化。

3. 上下文显式化

一句话定义：Agent 需要知道的信息，应该进入仓库，而不是停留在人脑、聊天记录和一次性 prompt 中。

它解决的问题是“每次都要重新解释项目”。如果一个任务必须靠维护者口头补充十条约定，说明这些约定已经是工程资产，却没有被版本化。

工程例子：仓库根目录放 AGENTS.md，告诉 Agent 常用命令、禁止修改范围、代码风格和验证流程；docs/architecture.md 写全局边界；模块 README 写局部职责；ADR 记录架构取舍；docs/testing-guide.md 说明测试分层；agent-notes.md 记录容易误改的坑。

可记住的总结：不要把工程记忆外包给一次性聊天窗口。

4. 验证闭环化

一句话定义：AI 可以生成代码，但正确性必须由测试、类型、lint、contract test、golden case、regression test 和 CI/CD 裁判。

它解决的问题是“模型说它对，但它没有资格自证正确”。Agent 很擅长解释自己的修改，也很擅长编出听起来合理的理由。工程系统不能把这种解释当成验证。

工程例子：修改订单金额计算时，必须跑单元测试、金额舍入 golden case、支付 provider contract test 和端到端 checkout regression test。CI 应该阻止没有对应验证记录的变更进入主分支。

可记住的总结：AI 负责提出变更，验证系统负责判决变更。

5. Hook 护栏化

一句话定义：当 Agent 拥有 shell、文件系统、MCP、数据库或云服务权限时，必须在关键节点设置 hook 护栏。

它解决的问题是“Agent 已经不只是补全器，而是有真实副作用的执行体”。一个能运行命令、改文件、访问数据库、调用云服务的 Agent，本质上已经进入自动化执行系统范畴。

工程例子：用 Codex hooks 或本地 hooks 在 PreToolUse 拦截危险命令，例如删除目录、修改生产配置、访问 secrets；在 PostToolUse 记录命令输出摘要；在 PreCompact 保存任务状态；在 Stop 生成审计摘要，包括变更文件、测试结果和未完成事项。

可记住的总结：不要只提醒 Agent 小心，要在它动手前把护栏装上。

6. 权限最小化

一句话定义：Agent 只能拿到当前任务需要的最小权限。

它解决的问题是“安全不能靠模型自觉”。如果 Agent 拿到了生产数据库 token、云服务 root key、线上 kubeconfig，那么一句 prompt 里的“不要乱来”没有工程意义。

工程例子：本地开发任务只给只读生产日志和 mock 数据，不给生产数据库写权限；部署任务使用短期 token；CI Bot 只能写评论不能合并；需要访问 secrets 的任务通过显式 approval 和审计记录完成。

可记住的总结：真正的安全边界，是让错误操作从权限上做不到。

7. Prompt 资产化

一句话定义：稳定有效的 prompt、review checklist、testing guide、refactor playbook 和 AI rules 应该版本化进入仓库。

它解决的问题是“团队把 prompt 当聊天技巧，而不是工程资产”。如果某个 review prompt 能稳定发现问题，它就应该像测试脚本一样沉淀下来。

工程例子：docs/ai-review-checklist.md 规定安全、兼容性、性能、测试覆盖和迁移风险检查项；docs/refactor-playbook.md 说明重构步骤；.cursor/rules、AGENTS.md、.codex/ 配置统一工具行为。

可记住的总结：好的 prompt 不是灵感，是可复用的工程协议。

8. 任务切片化

一句话定义：不要把大而模糊的任务直接丢给 Agent，要把任务拆成有目标、范围、验收标准和测试命令的小任务。

它解决的问题是“Agent 在大任务里容易漂移”。任务越大，Agent 越容易混合重构、功能实现、样式调整和无关清理，最后 diff 难审，风险难控。

工程例子：不要说“重构 checkout”。应该说：只调整 features/checkout/pricing 的折扣计算；禁止修改支付 provider；验收标准是保留现有 API、补充三组边界测试、运行 npm test -- checkout；输出包括 change summary 和风险列表。

可记住的总结：模糊任务会制造模糊 diff，模糊 diff 很难被信任。

9. 差异可审计化

一句话定义：每次 AI 修改都应该输出 change summary，说明改了什么、为什么改、行为是否变化、跑了哪些测试、剩余风险在哪里。

它解决的问题是“人类 reviewer 被迫从 diff 里倒推意图”。AI 生成的 diff 可能很大，如果没有变更叙事，reviewer 的成本会急剧上升。

工程例子：PR 模板要求填写 Behavior Change、Validation、Risk、Manual Review Needed。Agent 在任务结束时自动生成摘要，并把测试命令和结果写入 verification-log.md 或 PR 描述。

可记住的总结：可审计的变更，才有资格进入自动化流水线。

10. 状态落盘化

一句话定义：长任务不能只依赖 Agent 的对话记忆，任务状态要落盘。

它解决的问题是“上下文压缩后任务漂移”。Agent 的工作经常跨越多轮对话、多次命令、多次失败重试。如果状态只在聊天窗口里，压缩或中断后很容易丢失关键决策。

工程例子：用 .ai/task-state.md 记录当前目标、已完成步骤、阻塞点；current-plan.md 保存执行计划；decision-log.md 记录为什么选择某个方案；verification-log.md 记录跑过的命令、结果和失败原因。

可记住的总结：长任务的记忆不能靠上下文窗口续命。

11. 工具分层化

一句话定义：Cursor、Copilot、Codex、ChatGPT、CI Bot 不应该混为一谈，它们应承担不同职责。

它解决的问题是“所有工具都被当成一个 AI”。补全工具适合局部代码生成，IDE Agent 适合跨文件编辑，终端 Agent 适合运行命令和处理反馈，聊天模型适合设计讨论和解释，CI Bot 适合自动审查和守门。

工程例子：用 Copilot 写局部 boilerplate，用 Cursor 做 IDE 内重构，用 Codex 执行带验证闭环的任务，用 ChatGPT 讨论架构方案，用 CI Bot 检查 contract、测试覆盖、权限和变更摘要。

可记住的总结：AI 工具不是一个入口，而是一组分层执行器。

12. 人类裁决化

一句话定义：AI 是执行者、建议者和加速器，但最终业务判断、架构取舍、安全边界和质量责任属于人类。

它解决的问题是“把责任外包给模型”。模型可以给出方案，但不能承担线上事故、合规风险、用户损失和长期维护成本。

工程例子：Agent 可以提出是否拆分服务、是否引入消息队列、是否修改权限模型，但最终必须由人类 owner 判断业务收益、复杂度、迁移风险和组织承受能力。高风险变更必须保留人工 approval。

可记住的总结：AI 可以加速工程，但不能替人承担工程责任。

CI/CD：从交付流水线到可信变更流水线

传统 CI/CD 主要回答三个问题：能不能 build，测试过不过，能不能 deploy。Agent-native 时代，这还不够。

当越来越多代码由 Agent 修改，CI/CD 必须升级为可信变更流水线。它不只检查构建结果，还要检查变更是否遵守架构边界、是否破坏 contract、是否改变 golden behavior、是否附带 change summary、是否记录 verification log、是否越权访问资源、是否需要人工 approval。

一个 Agent-native CI 可以包含这些 gate：

• Architecture boundary：禁止跨层依赖、禁止绕过 domain API。
• Contract test：外部 API、事件 schema、数据库迁移必须兼容。
• Golden behavior：核心行为快照变化必须显式确认。
• Regression test：历史 bug 的 case 必须持续通过。
• Change summary：没有变更摘要的 AI diff 不能合并。
• Verification log：必须记录实际运行过的测试命令。
• Permission audit：检查是否修改 secrets、CI token、部署配置。
• Human approval：涉及权限、数据、计费、安全策略的变更必须人工批准。

换句话说，CI/CD 的目标不再只是“把代码送上线”，而是证明这次变更值得被信任。

实践落地：一个最小结构

下面是一个我认为比较实用的 Agent-native feature 结构：

features/
  checkout/
    contract.md
    schema.ts
    implementation.ts
    implementation.test.ts
    regression.test.ts
    behavior.golden.md
    mock-data.ts
    agent-notes.md

AGENTS.md
docs/
  architecture.md
  ai-review-checklist.md
  testing-guide.md
  adr/
.ai/
  task-state.md
  current-plan.md
  decision-log.md
  verification-log.md
.codex/
  hooks.json

contract.md 说明这个 feature 对外承诺什么；schema.ts 固化数据边界；implementation.ts 放实现；测试文件给出局部验证；behavior.golden.md 记录典型输入输出；mock-data.ts 让 Agent 不必临时编数据；agent-notes.md 写“这里为什么不能随便改”。

根目录的 AGENTS.md 是 Agent 的入口手册；architecture.md 是全局地图；ai-review-checklist.md 是审查协议；.ai/ 保存长任务状态；.codex/hooks.json 则把危险动作、状态保存和审计摘要接入工具链。

这套结构不追求仪式感。它的价值在于让 Agent 进入项目后，能更快回答三个问题：我在哪？我能改什么？我怎么证明自己没改坏？

结语：AI-native 是工程秩序的升级

AI-native 的核心不是“让 AI 写更多代码”。代码生成只是表层能力，真正难的是让变更变得可理解、可约束、可验证、可审计。

Human-native 项目依赖人的长期记忆。Agent-native 项目把这些记忆沉淀为架构、契约、测试、文档、hook、权限和流程。

未来的软件工程不会只比谁更会提示词，而会比谁的项目更适合智能执行体参与演化。一个混乱项目接入 AI，只会更快地产生混乱；一个结构清晰、上下文显式、验证闭环完善的项目，才会真正吃到 Agent 的效率红利。

AI-native 不是让 AI 更自由，而是让 AI 在清晰架构、显式上下文、原子结构、最小权限、自动验证和 hook 护栏中高效行动。