从零成长为 FDE

Appearance

Text-First Agentic Engineering（文本优先的智能体工程） ​

核心哲学：
代码只是实现，文本才是工程记忆。
在 Agent 时代，代码是极易生成的易耗品，唯有需求、决策、规范、执行轨迹与故障复盘沉淀为机器可读的文本上下文，系统才具备可维护性、可解释性与可持续演进的能力。

001

目录 ​

0. 时代背景与核心困境（Why Text-First?） ​

大语言模型（LLM）的爆发彻底重塑了编程的边际成本：编写单行代码的成本正在无限趋近于零，然而理解与维护系统的总认知成本却呈指数级上升。

在过去几年的企业级 AI 与前线交付（FDE）实践中，团队普遍遭遇了以下四大工程泥潭：

  1. 代码狂欢之后的工程崩溃（Code Without Context）：
    开发者或 Agent 依靠直觉在聊天框里疯狂生成代码，一旦遇到线上故障或需求变更，由于没有任何文本记录当初为什么这么写、依据什么业务口径，导致人类不敢改、Agent 瞎改，系统迅速退化为不可维护的“技术黑洞”。
  2. 上下文腐烂与认知漂移（Context Rot & Drift）：
    对话窗口一旦清空或会话过长，Agent 就会失忆；业务规则、数据库特殊字段枚举、历史 Bug 的教训散落在微信群聊、飞书会议或个人脑子里，每次给 Agent 派活都必须由工程师手工重新“科普”一遍。
  3. 千行巨型提示词的诅咒（Prompt Bloat）：
    试图将所有业务逻辑、边界情况、调用顺序硬塞进一个长达数千行的 Prompt（如 1500 行的 System Prompt），结果导致模型注意力稀释、规则相互打架、执行随机性失控。
  4. 完全自主 Agent 的失控幻觉（The Failure of Raw Autonomous Agents）：
    把开放的目标直接扔给一个全自动 ReAct 智能体，往往带来死循环、无效重试、Token 熔断、随意跳过业务硬校验，甚至在数据库报错时“友好地编造一个伪造数字”的灾难性后果。

根本根源在于：团队把重心放在了“让 Agent 直接写代码”，却忽视了“构建 Agent 执行所需的确定性工程事实”。
破解之道：必须从“代码优先（Code-First）”全面走向“文本优先（Text-First）”。

1. 体系化定义（Definition） ​

Text-First Agentic Engineering（文本优先的智能体工程） 是一种面向 AI Agent 时代的原生软件工程方法论：

将系统的需求、约束、设计、决策、执行过程、日志、测试及问题处理过程，以人类可读、机器可检索、可版本控制的结构化文本作为长期工程事实；人类工程师负责意图（Intent）与决策（Decision），Agent 基于这些事实进行规划（Planning）、执行（Execution）、验证（Verification）和复现（Replication）。

在该范式下，文档（Text）不再是事后补录的边缘负担，而是人机协作的第一介质与唯一真实来源（Single Source of Truth）。

2. 核心观点与哲学基石（Core Philosophy） ​

2.1 核心金句 ​

代码只是实现，文本才是工程记忆。
Agent 时代应将需求、决策、规范、执行轨迹与故障过程全部沉淀为机器可读的上下文，
由人类掌握意图与决策，由 Agent 基于完整上下文执行和验证。

2.2 核心哲学假定 ​

  1. 代码是易耗品（Disposable Artifacts）：
    在强大的代码生成模型面前，具体代码的生命周期大大缩短，随时可以根据最新规范被重写甚至全部重构。
  2. 文本是恒久事实（Perpetual Engineering Facts）：
    业务背后的“商业意图”、“为何选方案 A 而非方案 B 的权衡”、“踩过的严重生产坑点”才是最宝贵且不可替代的工程资产。
  3. 文本即代码，文本即接口（Text as Code & Text as Interface）：
    人类使用人类自然语言与 Markdown 表达意图与规范；Agent 使用自然语言与结构化协议（JSON/YAML）理解规范并输出工具调用。文本构成了人类高维思考与机器精确计算之间的通用桥梁。

3. 理论谱系与思想来源（Theoretical Genealogy） ​

Text-First Agentic Engineering 并非凭空捏造的空中楼阁，而是经典软件工程优秀思想在 AI Agent 时代的全面升维与集大成：

  • Docs as Code（文档即代码）：
    文档进入 Git 仓库，与代码同源同库同提交；享受代码审查（Code Review）、自动化格式校验与版本历史追踪。在 Agent 时代，它进一步成为 Agent 可随时通过文件读取获取的基础资产。
  • Spec-Driven Development（SDD，规格驱动开发）：
    严禁未出 Spec 就开始编码。将意图、输入输出契约、边界条件提前写成严谨规范，Agent 面向 Spec 进行编码，避免基于模糊 Prompt 的猜测性开发。
  • Architecture Decision Record（ADR，架构决策记录）：
    详细记录“背景是什么、权衡了哪些备选方案、为什么最终选择该方案、有哪些后续影响”。ADR 为 Agent 提供了宝贵的“负向知识”与“决策上下文”，彻底避免 Agent 反复提议已被证明不可行的方案。
  • Requirements Traceability（需求可追踪性）：
    建立 Requirement (PRD/Issue) → Spec → ADR → Code (Commit/PR) → Test → Incident (Bugfix) 的双向因果链路，使得系统任何一处代码都能找到对应的业务起源。
  • Observability / Execution Trace（可观测性与执行轨迹）：
    将 Agent 的 Prompt 输入、工具调用序列、中间推演步骤、真实执行耗时结构化落盘（如 Harness Log），使黑盒的 Agent 行为白盒化，支持事后一键重放和评测。
  • Context Engineering（上下文工程）：
    不再依赖粗暴的“把全库塞进上下文窗口”，而是将工程事实组织为高度模块化、机器可索引切片的知识网，按需动态编译输入给 Agent。

核心变革：传统软件工程中，文档只是“人给人看的说明书”；而在 Text-First 中，文档升级为**“人类与 Agent 共享的长期工程记忆和执行法定依据”**。

4. 七大工程原则深度剖析（The 7 Principles） ​

002

markdown
1. Text First
   重要事实优先文本化。

2. Spec as Source of Intent
   Specification 是意图的权威来源。

3. Decision with Provenance
   不只记录决定，还记录为什么决定。

4. Trace Everything
   Requirement → Decision → Code → Test → Incident 全链路追踪。

5. Repository as Shared Memory
   Repo 不只是代码仓库，也是 Human + Agent 的共享长期记忆。

6. Human Decides, Agent Executes
   人负责 Goal / Constraint / Trade-off，
   Agent 负责 Implementation / Exploration / Verification。

7. Context is Compiled, Not Re-explained
   AI 上下文从工程事实中动态组装，而不是每次人工重新 Prompt。

原则 1：Text First（重要事实优先文本化） ​

  • 内涵：任何未写入版本库文本的沟通、口头约定、排错经验都不算事实。所有的业务规则、字段含义、脏数据补丁，都必须落盘为结构化 Markdown 或代码资产。
  • 反模式：“这几个字段的计算口径张工最清楚，微信问他一下”、“这次改动没写文档，看提交日志的补丁吧”。
  • 最佳实践：发现新业务口径或数据特例时，首要动作是在 docs/ 或 specs/ 中提交一条文本更新，然后再交由 Agent 根据该文件生成代码。

原则 2：Spec as Source of Intent（Specification 是意图的权威来源） ​

  • 内涵：Agent 不直接从零散闲聊或粗糙提问中写代码，而必须从一份结构严谨的 Specification 中汲取意图。Spec 是包含前置条件、后置条件、错误边界与验收标准的“法定合同”。
  • 反模式：直接贴一段需求给 Agent 说“帮我实现一个问数接口”，然后反复通过对话纠偏“不对，这里少考虑了唯品会渠道”。
  • 最佳实践：编写 spec.md 确定业务参数、计算规则、SQL 模板契约与预期测试用例，让 Agent 面向 spec.md 开展编码和单元测试。

原则 3：Decision with Provenance（决策附带因果溯源） ​

  • 内涵：单纯记录“我们要用 MySQL”毫无价值，必须记录“为什么选择 MySQL、放弃了 ClickHouse 的原因、是在何种数据量和部署资源约束下的妥协”。
  • 反模式：架构设计只写结论，三个月后新成员或 Agent 重新介入，又重新提出了被否决过的方案。
  • 最佳实践：每次重大技术架构或业务逻辑变更，强制提交一份 ADR 文档（包含 Context, Alternatives Considered, Decision, Consequences），成为 Agent 决策树上的硬剪枝依据。

原则 4：Trace Everything（全链路因果追踪） ​

  • 内涵：软件全生命周期的每个实体都必须具备唯一可追溯链条：Issue/PRD⟶Spec⟶ADR⟶Code/PR⟶Test⟶Trace/Log
  • 反模式：线上出现一个指标计算异常，不知道对应的代码由哪个需求引入、为什么这么算、通过了什么测试。
  • 最佳实践：每一个 Commit 和测试报告必须带有关联的 Issue 号与 Spec 条目锚点；Agent 产生的每次修复必须生成对应的 Regression Test 与复盘记录。

原则 5：Repository as Shared Memory（仓库是人机共享的外部长期记忆系统） ​

  • 内涵：Git 仓库不仅保存可执行代码，更承载系统的“外脑”。包括：项目背景、架构设计、排错日志、业务实体映射、提示词调优历史、Agent 行为规范。
  • 反模式：模型执行的历史日志在终端跑完就关掉，Bug 排查经验全留在工程师的个人笔记软件中。
  • 最佳实践：将 memory/、devlogs/、harness_logs/ 规范化纳入仓库管理，使任意新会话的 Agent 都能在克隆代码后直接继承整个项目的历史心智。

原则 6：Human Decides, Agent Executes（人定意图约束，Agent 负责推演执行） ​

  • 内涵：人类工程师的价值不在于手打循环语句，而在于：
    • 定义清晰的目标（Goal）；
    • 划定不可逾越的安全红线与业务边界（Constraint）；
    • 在冲突的目标间做商业权衡（Trade-off）。
      Agent 则负责：
    • 方案细节探索与代码草拟（Exploration & Implementation）；
    • 编写全面的测试用例与边界验证（Verification）；
    • 多场景执行复现（Replication）。
  • 反模式：让人类去写样板代码，却让 Agent 自主做架构权衡和业务口径认定；或者人类对 Agent 的输出缺乏自动化检验手段，盲信盲推。
  • 最佳实践：人类编写验收断言与不可逾越红线，Agent 负责跑通实现并出具执行凭据。

原则 7：Context is Compiled, Not Re-explained（上下文动态编译，拒绝反复口述） ​

  • 内涵：给 Agent 的上下文不应依赖人类在 Chat 对话框中的记忆和手动复制粘贴，而应该像编译源码一样，由工具自动从仓库的工程事实文件（Spec, DDL, ADR, Rules）中抽取并组装成紧凑、精准的上下文切片。
  • 反模式：每次开新窗口都要向模型重新交代：“我们项目使用的是 Python 3.11，SQLAlchemy 2.0，表 A 和表 B 的关联字段是 xxx”。
  • 最佳实践：建立结构化的上下文规则（如 AGENTS.md、CLAUDE.md、.rules/），开发阶段由自动化流水线按任务意图动态组装 Prompt Context，实现零废话启动。

5. 系统三层架构模型（3-Layer Architecture Model） ​

003

为了让 Text-First Agentic Engineering 可落地，我们将系统划分为清晰的三层架构：

+-------------------------------------------------------------------------+
|                         1. 意图与决策层 (Intent Layer)                  |
|   - PRD / User Story               - System Specifications (Specs)      |
|   - Architecture Decision (ADRs)   - Business & Metric Dictionaries     |
|   [人类所有，负责目标、边界、权衡，经由 Code Review 严格审计]           |
+-------------------------------------------------------------------------+
                                     │
                                     ▼ (动态检索 / 上下文编译器)
+-------------------------------------------------------------------------+
|                     2. 上下文与记忆层 (Context & Memory Layer)          |
|   - Repository Shared Memory       - Field / DDL Profiling Metadata     |
|   - Domain Knowledge Rules         - Bug & Incident Knowledge Base      |
|   - Prompt Assets & Guidelines     - Structured Session State Store     |
|   [面向人类与机器双向可读，支持机器索引、按需切片、动态投影]           |
+-------------------------------------------------------------------------+
                                     │
                                     ▼ (分发至受控子智能体 / 工作流节点)
+-------------------------------------------------------------------------+
|                   3. 执行与验证层 (Execution & Verification Layer)       |
|   - Deterministic Workflow DAG     - Subagents (Coder / Reviewer)       |
|   - Test Harness (TDD / Regression)- Fail-Closed Gateways & Evaluator   |
|   - Observability Tracing & Replay - Automated Git Commits & PRs        |
|   [Agent 负责推演与实现，强类型网关守门，测试用例自动化闭环验证]        |
+-------------------------------------------------------------------------+

6. 标准化工程实施闭环（The 5-Stage Agentic Lifecycle） ​

004

在 Text-First 体系下，一次功能开发或 Bug 修复严禁跳过任何环节，遵循严格的五阶段闭环：

Stage 1: Grounding & Profiling（地基探查与事实扎根） ​

  • 在写任何需求前，禁止空谈脑补。必须先运行探查脚本扫描真实生产环境（如扫描数据库空值率、主外键、实体别名字典、错误日志）。
  • 将探查结果生成为第一份文本基线（Profiling Report）。

Stage 2: Specifying & Decision（意图固化与规格书写） ​

  • 将业务诉求转化成明确的 spec.md：
    • 核心输入输出参数类型与样例；
    • 确定性逻辑流程（推荐以工作流 DAG 描述）；
    • 涉及的架构变更以 ADR 形式归档。

Stage 3: Context Compilation & Targeted Execution（上下文定向编译与执行） ​

  • 将 Spec、关联的 ADR、最小依赖 DDL 编译为目标任务上下文，注入专用 Subagent。
  • Subagent 优先编写基于契约的测试用例（TDD 模式），然后生成最小可用实现。

Stage 4: Harness Verification & Gatekeeping（双重守护与测试验收） ​

  • 严禁依赖模型的口头承诺（“我已修复并测试成功”）。
  • 必须通过预置的本地验证脚本（Test Harness / Docker 隔离环境）实际运行，输出真实终端退出码与测试断言结果。
  • 遵循“失败即停（Fail-Closed）”原则，若运行异常立即阻断并暴露给人类。

Stage 5: Trace Logging & Memory Distillation（轨迹归档与记忆蒸馏） ​

  • 修复成功后，将排错轨迹、解决策略沉淀为 devlogs/ 或 docs/bugs/ 文档。
  • 更新项目根目录的规则文件（如 AGENTS.md），使后续智能体继承该教训，完成工程记忆的正向飞轮演进。

7. 标准文本工件契约规范（Artifact Contracts） ​

为保证机器和人类对文本解析的一致性，Text-First 工程约定以下标准 Markdown + YAML Frontmatter 工件：

7.1 规格工件模板（specs/FEATURE-XXX.md） ​

markdown
---
id: SPEC-20260907-01
title: 品牌销售额统一指标网关构建
author: fde-engineer
status: approved
created_at: 2026-09-07
trace_refs:
  issue: "#102"
  adr: "docs/adr/003-unified-metric-gateway.md"
---

# 1. 业务目标与边界 (Intent & Scope)
- 目标：将驾驶舱大屏与 AI 问数的销售额计算口径统一收敛为单一指标网关。
- 显式非目标 (Out of Scope)：首期不支持未入驻品牌的跨平台预估测算。

# 2. 核心计算口径 (Formal Metric Formula)
$$
\text{GMV} = \sum(\text{pay\_amt}) - \sum(\text{refund\_amt})
$$
- 硬过滤条件：`order_status = 1 AND is_test = 0 AND store_type IN ('Tmall', 'Douyin')`

# 3. 接口与输入输出契约 (Contract)
- **Input Slot**:
  - `brand_name`: string (必须通过别名网关归一化)
  - `date_range`: [ISO_Date, ISO_Date]
- **Output Envelope**:
  - `metric_value`: float
  - `currency`: "CNY"
  - `as_of_time`: ISO_Timestamp

# 4. 验收测试用例 (Acceptance Assertions)
- [ ] 针对天猫 2026-07 百雀羚官方旗舰店，返回金额与财务对账表绝对差值 < 0.01 元。
- [ ] 传入歧义品牌名 "百雀" 时，网关必须抛出 400 AmbiguousEntityException，严禁兜底瞎算。

7.2 架构决策工件模板（docs/adr/ADR-XXX.md） ​

markdown
---
id: ADR-003
title: 采用状态机确定性工作流替代单一 ReAct 自主问数 Agent
date: 2026-09-07
status: accepted
deciders: [fde-lead, backend-architect]
---

## 背景 (Context)
在生产环境中，单 Prompt 驱动的 ReAct Agent 在处理复杂 SQL 关联与别名匹配时，死循环率达 18%，单次问答消耗超过 8000 Token 且偶发幻觉。

## 备选方案对比 (Alternatives Considered)
1. **继续优化 System Prompt**：增加思维链示例。缺点：提示词过长导致注意力漂移，无法杜绝幻觉。
2. **纯自主 Code-Interpreter Agent**：让模型手写 Python 执行。缺点：对不可信生产数据库存在注入与宕机风险。
3. **确定性状态机工作流 (Stateful Workflow DAG)**：将意图识别、槽位填充、别名查找、模板 SQL 拼装拆分为固定节点。

## 决策 (Decision)
采纳方案 3。大模型仅保留为意图分类器与结果润色器，核心数据路由、别名网关与 SQL 生成使用确定性代码构建。

## 影响与后果 (Consequences)
- 积极影响：准确率提升至 99%，平均延迟下降 65%，杜绝 SQL 注入与死循环。
- 消极影响/代价：新增指标时需要维护 Python 模板代码，灵活性略微降低。

8. 软件工程范式横向对比矩阵（Paradigm Comparison） ​

比较维度传统代码优先 (Code-First)裸智能体/提示词工程 (Prompt-First)文本优先智能体工程 (Text-First Agentic)
核心工程产物源码、二进制包庞大的 System Prompt、聊天记录结构化文本契约 (Spec/ADR/Trace)
意图与需求来源人口头传达 / 零散 Jira 票据用户的即兴自然语言提问经审计版本化的 Spec 与指标字典
Agent 的角色无（仅作为辅助代码补全）黑盒全知全能决策者受工作流与测试契约严格约束的执行器
上下文维护方式存活在人类工程师脑中随 Session 销毁丢失，频繁超长断流从 Git 仓库动态索引编译最小切片
质量保证手段人工编写单元测试人工肉眼抽检 Agent 生成结果Test Harness + 断言契约 + Fail-Closed 网关
可复现与可维护性依赖人员稳定，换人易断代极差，Prompt 微调引发雪崩效应极高，执行轨迹与因果全流程落盘可回放
对极端复杂度的应对堆砌人月工程概率崩溃、严重幻觉分治治理：人类管意图，机器管推演

9. FDE 前线部署工程师实战指南（FDE Field Manual） ​

005

作为面对复杂客户系统、受限专有网络与多变业务口径的前线部署工程师（FDE），Text-First 是扎实推进交付、保障系统高可维护性的核心工程基石：

现场四大工程准则（The 4 Field Rules） ​

  1. “不看口头怎么说，只看 Excel 怎么算”：
    现场业务人员往往无法清晰抽象规则。先拿真实对账 Excel，将其中的公式与条件用结构化文本逆向工程写出第一版 metrics_spec.md。
  2. “把脏数据挡在模型之前”：
    坚决不要试图用自然语言在 Prompt 里教 Agent“遇到空值跳过、遇到重复表自己去重”。必须在数据层物化清洗，将结构以规范事实（Schema Specs）提供给 Agent。
  3. “先定验收 Harness，再让 Agent 动工”：
    在让 Agent 写功能代码之前，先编写能打穿环境的运行脚本和断言测试。Agent 交付的标准是：“运行 Harness 退出码必须为 0”，不接受任何“理论上可以”的口头回答。
  4. “每一次现场问题排查，必须沉淀为一条长效回归防线”：
    在生产环境处理完一次线上问题，绝不能拍拍屁股走人。必须完成闭环三步法：
    • 编写 bugs/YYYY-MM-DD-xxx.md 记录真实上下文；
    • 补充一条阻断该问题复发的单元回归测试；
    • 将避免该错误的设计原则同步到项目全局知识库。

10. 常见陷阱与避坑准则（Anti-Patterns & Pitfalls） ​

  • ❌ 陷阱 1：文档形式主义（Paperwork Bureaucracy）
    表现：为了写文档而写文档，编写通篇无实质内容的模板废话。
    准则：所有的 Text 必须是面向 Agent 可执行或可约束的。不能被机器用来做判断、生成或断言的纯空话，一律删除。
  • ❌ 陷阱 2：Prompt 巨石化（Monolithic Prompt Trap）
    表现：把所有业务规矩塞进一个不断膨胀的系统提示词，坚信“大模型只要加了 CoT 就能解决一切”。
    准则：超过 100 行的业务 Prompt 必须立刻拆解为确定性工作流节点或结构化 Spec 模块。
  • ❌ 陷阱 3：伪自动化断言（The Hallucinated Verification）
    表现：Agent 回复“我已经修复了这个 bug，并且测试了全部通过”，但实际未触发任何执行命令。
    准则：无独立环境输出证据，即视为未完成。必须依赖本地真实的进程运行日志和机器断言结果。

11. 结语与未来展望（Conclusion） ​

006

软件工程发展六十年，编程范式历经了从机器码、汇编语言、高级命令式语言，到面向对象、声明式编程的数次跃迁。每一次演进的本质，都是人类表达意图的抽象层次在不断提高，而具体机器实现的下沉成本在不断降低。

Text-First Agentic Engineering 揭示了 AI 时代的软件工程终局：

  • 编程语言不再是人类思考的紧身衣；
  • 自然语言与形式化文本成为了人类与机器共同思考、演进系统的统一中枢；
  • 代码成了流动的执行介质，而沉淀在仓库中的规范、决策、上下文与执行记忆，构成了软件生命力的永恒本体。

从今天起，做一名具备 Text-First 信仰的工程师：

善待你的每一篇 Spec，记录你的每一次决策，全链路追踪你的每一次执行。
把自由留给思考，把确定性留给工程。

基于百雀羚真实数字化交付场景总结 · 代码只是实现，文本才是工程记忆

Copyright © 2026 Project FDE-Zero-to-Hero