AI 编程范式转换与 Memory 工程：从无状态模型到 AGENTS.md 声明式配置

简介：模型是无状态的推理函数，Harness 是有状态的编排器，人要做的是写规范、验结果；AGENTS.md 这类 Memory 文件用声明式配置让 Agent 读懂项目，并在上下文压缩后持续生效

范式转换：从写代码到写规范

简介：Software 3.0 时代编程不再等于写代码，80% 时间想清楚要什么，20% 时间验证 AI 做得对不对

• Software 三代演进

• 范式转换的本质：你不再是代码的生产者，而是意图的传达者和质量的把关者

• 时间分配的变化

• 编码时间压缩到 20%，规划和测试时间翻倍，新比例约为 Planning 40%、Coding 20%、Testing 40%

• 启示：需要更强的架构设计能力和验证能力

• 设计反转（Design Inversion）

  • 传统：人写代码，AI 辅助
  • 新范式：人写规范，AI 写代码
  • 80% 时间想清楚要什么（写规范），20% 时间验证 AI 做得对不对

• 实现力高原（Implementation Plateau）

  • AI 写代码的能力已进入高原期，SWE-bench 的代际提升只有个位数百分比，不是不进步，而是够用了
  • 十个人用同样的模型、同样的额度，产出差异可以有十倍，区别在规范
  • 瓶颈不在模型，在你能不能把需求说清楚

• 核心观点

  • 编程 ≠ 写代码
  • 编程 = 设计意图 × 精确表达 × 验证产出，循环是 Design、Prompt、Validate、Iterate

底层架构：规范、Harness、模型三层

简介：你写的三层规范被 Harness 加载，Harness 再调用无状态模型，三层各司其职

• 关键点
  • 代码两年就淘汰，设计思想用一辈子，跑通固然可喜，理解架构才是核心收获
  • 学概念、学思想，不绑定任何一个工具

AI Coder 工具全景与概念映射

简介：主流 AI 编程工具都实现了 Harness，六大工程化能力一一对应，差别在开源程度和国产模型支持

• 工具全景（2025~2026）

• 工程化能力六维对比

• OpenCode 与 Claude Code 概念映射

• 为什么以 OpenCode 为主线
  • MIT 开源，代码完全公开，可学习架构设计、可二次开发
  • 100K+ Stars，社区活跃，问题有人答
  • 国产模型原生支持，DeepSeek / Qwen / GLM / Kimi 零成本接入
  • 概念映射完整，与 Claude Code 六大能力一一对应
  • 安装遇到问题时，Cursor、通义灵码、Trae、Claude Code、Cline 等任意工具都能替代，AI 辅助开发的道理相通

工程思想：无状态推理 + 有状态编排

简介：模型是极其强大但完全被动的推理函数，编排器给它加上循环、记忆和行动，才变成一个系统

• 模型的本质：无状态函数
  • 大语言模型 =f(input) → output，每次调用都独立，没有记忆、没有状态
  • 三个关键约束

• 编排器的本质：有状态系统（Harness）

• 红色节点是模型唯一参与的一步，其余都由 Harness 完成，绿色是退出条件
• 编排器 =while True: 观察 → 思考 → 行动 → 更新状态
• Harness 本意是马具，马有力气但没有马具拉不动车，Harness 改变的是力量的传导方式
• Harness = 编排器 + 规范化，包含 Tools、Knowledge、Observation、Action Interfaces、Permissions
• 三个模型没有的核心能力

• OpenCode / Claude Code / Cursor 本质都是编排器，负责管理状态、调度模型、执行工具、维护上下文，并提供权限系统保证运行时安全

• 被低估的关键能力：上下文管理

• 红色节点是规范持久生效的秘密

• 模型上下文窗口有限，真实任务很快撑满，Harness 的解法是自动压缩 + 重注入

• 不是模型记住了规范，是 Harness 在每次压缩后都重新塞给模型

• 一个重要命题

  • Harness 比模型更重要：同一个模型在不同 Harness 中的表现差距，远大于不同模型在同一个 Harness 中的差距
  • 调教 Harness 的能力 = 真正的杠杆点

• 实战验证：裸 API 调用 vs OpenCode 编排

importos, json, urllib.requestAPI_KEY=os.environ.get("DEEPSEEK_API_KEY","")API_URL="https://api.deepseek.com/chat/completions"defcall_api(prompt:str)->str:data=json.dumps({"model":"deepseek-chat","messages": [{"role":"user","content": prompt}],"max_tokens":1000,}).encode("utf-8")req=urllib.request.Request(API_URL, data=data, headers={"Content-Type":"application/json","Authorization":f"Bearer{API_KEY}",})withurllib.request.urlopen(req)asresp:returnjson.loads(resp.read().decode())["choices"][0]["message"]["content"]# 让它分析当前项目：裸 API 只会回答“请提供代码”或“我无法访问文件”print(call_api("请分析当前项目的目录结构和代码质量，给出改进建议。"))

• 同一个问题在 OpenCode 里问，它会用 Glob / Read 扫描目录、读取文件内容，基于真实文件给出具体建议

• 关键洞察：模型是同一个模型，差别在于编排器赋予了它感知和行动的能力

实战项目：AI 知识库助手系统

简介：一个人加一个 AI Agent 团队，搭出一个从采集到分发的知识管理系统，分四个版本渐进演进

• 四大核心能力

• 技术栈：OpenCode 编排 + 国产模型推理 + MCP 工具集成

• V1 到 V4 渐进演进

• V1 的四个主题

环境搭建：OpenCode + 国产模型

简介：Node.js 18+ 装 OpenCode，配一个国产模型的 API Key，首次对话成功即可

• 安装

# macOSbrewinstall node&&node--version# 需要 18+npminstall-gopencode-ai@latest# 或 curl -fsSL https://opencode.ai/install | bashopencode--version

• 国产模型 API Key

echo'export DEEPSEEK_API_KEY="sk-你的key"'>>~/.zshrc# bash 用 ~/.bashrcsource~/.zshrc&&echo$DEEPSEEK_API_KEYmkdir~/opencode-test&&cd~/opencode-test&&opencode# 输入“你好，请回复 OK 确认连通”

• 注意点
  • API Key 只显示一次，创建后立即复制保存
  • 自查清单：Node 18+、opencode --version有输出、Key 已获取、环境变量已配置、首次启动成功、对话回复 OK

Memory 工程：让 Agent 拥有持久记忆

简介：Memory 是一个纯文本配置文件，每次会话自动加载进提示词，相当于新员工入职读的项目开发手册

• 两种记忆

• Memory 不是数据库，是声明式的意图描述文件

• 没有 Memory vs 有 Memory

• 各工具的 Memory 文件

• Claude Code 用户把文件命名为CLAUDE.md，效果相同

工程思想：声明式配置优先

简介：告诉系统要什么而不是怎么做，规则放进文件，可审计、可版本控制、可协作

• 命令式 vs 声明式

• 为什么声明式更适合 AI Agent

• 两种写法对比

# 命令式：用代码控制 Agent 的每一步行为defconfigure_agent(agent):agent.set_language("python")agent.set_style("google")agent.add_rule("always_add_docstring",True)agent.add_rule("max_function_length",50)agent.set_naming_convention("snake_case")agent.add_forbidden_pattern("print()")# 问题：规则散落在代码里；改规则要改代码重新运行；非程序员无法参与；换框架要重写

# AGENTS.md — 声明式：描述要什么## 技术栈-语言: Python 3.12-框架: FastAPI + Uvicorn## 编码规范-遵循 Google Python Style Guide-所有函数必须有 docstring-函数不超过 50 行，使用 type hints-变量命名: snake_case-禁止裸 print()，使用 logging 模块

• 核心价值
  • 描述要什么而非怎么做，让 Agent 自己决定最优执行路径
  • 可审计、可版本控制、可协作，三位一体的工程化保障

AGENTS.md 实战：六个组成部分与上下文管理

简介：AGENTS.md 是 SDD 三层规范的第一层，按六个部分写，控制篇幅，重要规则放前面

• 从 Memory 到规范驱动开发（SDD）

• 六个组成部分

• 知识库项目的 AGENTS.md（参考实现）

# AGENTS.md — AI 知识库助手项目规范## 项目概述个人 AI 知识库助手系统。自动从 GitHub Trending、Hacker News 采集内容，AI 分析后结构化存储，支持多渠道分发。## 技术栈-语言: Python 3.12-AI 编排: OpenCode + 国产大模型（DeepSeek/Qwen/GLM/Kimi）-工作流: LangGraph-部署: OpenClaw-依赖管理: pip + requirements.txt-版本控制: Git## 编码规范-遵循 PEP 8，变量 snake_case，类名 PascalCase-所有函数必须有 docstring（Google 风格）-禁止裸 print()，使用 logging 或写入文件-禁止 import *，文件编码统一 UTF-8## 项目结构ai-knowledge-base/├── AGENTS.md — 项目规范（本文件）├── .opencode/│ ├── agents/ — Agent 角色定义文件│ └── skills/ — 可复用技能包├── knowledge/│ ├── raw/ — 原始采集数据（JSON）│ └── articles/ — 结构化知识条目（JSON）├── pipeline/ — 自动化流水线└── workflows/ — LangGraph 工作流## 内容规范-摘要中文、不超过 100 字，技术术语保留英文原文-评分 1-10：9-10 改变格局，7-8 直接有帮助，5-6 值得了解## 知识条目格式必填字段：id, title, source_url, summary, tags, statusstatus 可选值：draft / reviewed / published## Agent 角色概览|角色|文件|职责||------|------|------||采集 Agent|.opencode/agents/collector.md|从外部源采集技术动态||分析 Agent|.opencode/agents/analyzer.md|深度分析和价值评估||整理 Agent|.opencode/agents/organizer.md|去重、格式化、归档|## 红线（绝对禁止）-不编造不存在的项目或数据-不在日志中输出 API Key 或敏感信息-不执行 rm -rf 等危险命令-不修改 AGENTS.md 本身（除非明确要求）

{"id":"2026-03-01-github-openclaw","title":"OpenClaw: 开源 AI Agent 运行时","source":"github-trending","source_url":"https://github.com/example/project","collected_at":"2026-03-01T10:00:00Z","summary":"一句话中文摘要（不超过 100 字）","analysis":{"tech_highlights":["多 Agent 路由","50+ 平台支持"],"relevance_score":9},"tags":["agent","runtime","open-source"],"status":"draft"}

• 红线部分守住底线，知识条目格式让所有 Agent 的产出可以互相读懂，这也是AGENTS.md和普通 README 的区别

• 编码规范注入（详细版）

## 编码规范 (详细版)### 命名规则-文件名: kebab-case (如 user-service.py)-类名: PascalCase (如 UserService)-函数/变量: snake_case (如 get_user_by_id)-常量: UPPER_SNAKE_CASE (如 MAX_RETRY_COUNT)-私有方法: 前缀下划线 (如 _validate_input)### 必须遵守-每个函数不超过 30 行，每个文件不超过 300 行-所有公开函数必须有 docstring (Google 风格)-所有 API 返回统一格式: {"code": 0, "data": ..., "msg": ""}### 禁止事项-禁止 print() 调试，使用 logging-禁止 import *-禁止在循环中进行数据库查询 (N+1 问题)-禁止硬编码密钥或密码

• 上下文管理策略

• 效果演示：同一条指令的产出差异

• 验证 Memory 是否加载

  • 启动 OpenCode 后问“请告诉我这个项目的技术栈和编码规范”，检查回答是否包含 Python 3.12、PEP 8、snake_case、禁止裸print()、目录结构
  • 对比实验：把AGENTS.md临时改名为AGENTS.md.bak，用完全相同的提示词再生成一次，比较命名、docstring、日志、错误处理、文件位置

• 注意点

  • 对比实验后务必把 AGENTS.md 改回来，后续实操都依赖它
  • 做无 Memory 对比时要同时删掉上一轮生成的文件，否则会相互影响，足够聪明的 AI Coder 也可能去参考备份文件
  • 发现 Agent 产出不符合期望，先想AGENTS.md缺了哪条规则，补上去

SDD 强化：手写第一份 spec 与 grill-me 追问

简介：SDD 不需要装任何工具，核心是 Specify、Clarify、Implement 三阶段闭环，缺的不是模板而是一个会追问你的对手

• 三阶段闭环

• 红色节点是 SDD 和直接发一段话让 AI 干活的本质区别，绿色是让两周后还记得的关键

• Clarify 阶段 AI 的每个追问都给推荐答案，可以接受、改成自己的，或说“你决定”放权

• spec 模板：四个 H2

# AI 知识库 · 项目愿景 v0.1## 要做什么-每天抓取 GitHub Trending（? 多少条 · 只 AI 相关？）-用 Agent 分析内容（? 分析什么 · 输出啥）-输出知识条目（? JSON 还是 Markdown · 字段有哪些）## 不做什么## 边界 & 验收## 怎么验证

• 留下的?是下一阶段给 AI 质询的靶子

• 这份愿景 spec 最终变成AGENTS.md的项目定义段，编码规范 spec 变成AGENTS.md的编码规范段

• grill-me：让 AI 变成面试官

  • 来自 Matt Pocock 的开源技能集，6 行 Markdown，装完 AI 会一条条拷问AGENTS.md里的模糊点

npxskills@latest add mattpocock/skills/grill-me-aopencode# Claude Code 用 -a claude-codels~/.opencode/skills/grill-me/SKILL.md# 装完重启 CLI

• skill 靠SKILL.md里的description字段自动触发，不需要/skill前缀，直接说 “grill me on my AGENTS.md”

• 用法：先在specs/coding-standards.md写粗糙版（black 格式化、strict mode、覆盖率 ≥ 80%、不允许 TODO 进 main），再让 grill-me 追问，最后把结论写进AGENTS.md

• 直接聊（A 路）vs SDD 闭环（B 路）

• 多花的 25 分钟不是额外开销，是把调试 2000 行代码的成本提前投入在澄清需求阶段
• A 路输在没想到的就漏了，例如规范里根本没写行宽，同事抱怨时才发现
• grill-me 的价值不是直接帮你写，是帮你发现你没想到的

面试/考试记忆点

• 编程 = 设计意图 × 精确表达 × 验证产出，80% 想清楚要什么，20% 让 AI 实现
• 三层架构：你写的 SDD 规范、Harness 运行时、无状态模型，上层加载下层调用
• 模型是无状态函数，三个约束是无记忆、无决策、无行动
• Harness = 编排器 + 规范化，补上循环、记忆、行动三个能力，while True: 观察 → 思考 → 行动 → 更新状态
• Harness 比模型更重要，同一模型换 Harness 的差距远大于换模型
• 规范一直有效的原因是 Harness 在每次上下文压缩后重新注入AGENTS.md
• Memory 不是数据库，是声明式的意图描述文件，相当于项目入职手册
• 声明式写 What 不写 How，可审计、可版本控制、可协作、可迁移、可组合、低耦合
• AGENTS.md六个部分：项目概述、技术栈、编码规范、项目结构、工作流程、特殊约束，控制在 500 行内，重要规则放前面
• SDD 三阶段 Specify、Clarify、Implement，spec 里故意留?给 AI 追问