我用 AI 写代码的这一年：从“打字快“到“脑子清“

是发财不是旺财

509人浏览 · 2026-06-04 11:14:02

是发财不是旺财 · 2026-06-04 11:14:02 发布

我用 AI 写代码的这一年：从"打字快"到"脑子清"

先说我用的工具栈
一、别让 AI 猜你的规矩，写下来
二、Trellis：把"一个想法"变成"一段可追溯的代码"
三、Codegraph：比 grep 聪明一百倍的代码搜索
四、grill-with-docs：在写代码之前，先把话说清楚
五、MCP：让 AI 长出"手"
六、Agent Memory（docs/agent.md）：不只是"写文档"
七、我的日常开发节奏（真实流程）
八、几条"血泪教训"
九、如果你也想搭这套流程
最后说两句

摘要：用 AI 写代码一年，我从"让 AI 帮我写函数"进化到"让 AI 当自主工程师"。本文首次公开我的完整 AI 开发工作流：用 Rules + Spec 双轨制 让 AI 不再猜规矩，用 Trellis 把每个想法变成可追溯的代码，用 Codegraph 实现比 grep 快百倍的代码搜索，用 grill-with-docs 在写代码前厘清概念边界，用 MCP 让 AI 长出"手"去调外部工具。文章包含真实开发节奏、血泪教训和最小可行配置清单，适合所有想从"AI 辅助编程"跃迁到"AI 驱动开发"的工程师。

先说我用的工具栈

先列一下我日常打交道的东西，不然后面聊起来你都不知道我在说什么：

工具	干什么的	我的评价
Claude Code	AI 编程助手（主力）	目前用过最靠谱的，理解力强、不瞎编
Codegraph	代码知识图谱	秒查符号、追踪调用链，比 grep 快一个数量级
Trellis	项目管理 + 规范注入	把"脑子里的约定"变成"AI 自动读的文档"
grill-with-docs	领域建模审查	在写代码前逼你先把概念理清楚
MCP	外部工具集成协议	让 AI 能调外部 API/工具，扩展能力边界

如果你只用过 ChatGPT 网页版写代码，这篇文章可能会让你觉得"卧槽还能这样"——因为我第一次配好这套流程的时候就是这个感觉。

一、别让 AI 猜你的规矩，写下来

痛点

最开始用 AI 写代码的时候，每次对话都像在带新人：

“这个项目用 structlog 别用 logging”
“测试代码放 /test 目录”
“不要主动 commit”
“改完代码记得更新 docs/agent.md”

同样的话我要在不同对话里说八百遍，烦死了。

解法：Rules + Spec 双轨制

我把这些规矩分了两层：

第一层：Rules（.claude/rules/）——管"怎么写代码"

.claude/rules/
├── logging-style.md           # 必须用 structlog
├── langgraph-standards.md     # 框架层别硬编码业务字段
├── architecture-decisions.md  # 架构决策记录
├── known-risks.md             # 已知坑
└── ...

这些都是 Markdown，AI 每次对话会自动加载。写清楚"禁止做什么"比写"应该做什么"更有用——AI 对否定句更敏感。

第二层：Spec（.trellis/spec/）——管"这个包/层怎么写"

.trellis/spec/
├── backend/
│   ├── index.md              # 开发前检查清单 + 质量检查
│   ├── error-handling.md     # 怎么处理错误
│   ├── logging-guidelines.md # 日志规范
│   └── ...
├── guides/
│   ├── code-reuse-thinking-guide.md
│   └── cross-layer-thinking-guide.md

区别是什么？

Rules：全局的、跨项目的——比如"我所有的 Python 项目都用 structlog"
Spec：这个具体项目的——比如"这个项目的 API 返回格式是 {code, data, message}"

实战场景：我用 /trellis-before-dev 这个 skill，它在写代码前自动读取相关 spec 注入上下文。相当于每次写代码前先看一遍"项目开发手册"，而且不用我手动翻。

关键认知

Spec injected, not remembered（规范靠注入，不靠记忆）

不要把约定放在你的脑子里或者某个"团队 Wiki"里——AI 读不到就等于不存在。写在 .claude/rules/ 或 .trellis/spec/ 里，AI 每次对话自动加载。

二、Trellis：把"一个想法"变成"一段可追溯的代码"

为什么需要这个

你肯定遇到过这种情况：

AI 写了一半，你发现方向不对，但已经改了好多文件
过了两周回头看，完全不记得当时为什么要那样改
同一个 bug 修了三次，每次都从零开始排查

Trellis 解决的就是"AI 辅助开发的流程管理"问题。

三阶段工作流

Phase 1: Plan    → 搞清楚要做什么（brainstorm + research → prd.md）
Phase 2: Execute → 写代码，过质量检查
Phase 3: Finish  → 沉淀经验 + 收尾

Phase 1：Plan（规划阶段）

# 1. 创建任务
python ./.trellis/scripts/task.py create "添加用户认证中间件"

# 2. 进入 brainstorm 模式，和 AI 一起理需求
# AI 会先读代码、了解上下文，然后一个一个问问题：
# "这个中间件要保护哪些路由？"
# "认证方式是 JWT 还是 API Key 还是都支持？"
# "未认证时返回 401 还是重定向到登录页？"

# 3. 如果涉及技术选型，AI 会 spawn 研究子 agent
# 比如调研"Python 里哪个 JWT 库最合适"

# 4. 需求确认后，curate implement.jsonl（告诉实现 agent 该读哪些 spec）
python ./.trellis/scripts/task.py start 06-04-添加用户认证中间件

产出物：

prd.md：完整的需求文档（目标、需求、验收标准、技术方案、不在范围内）
research/：技术调研结果
implement.jsonl：实现 agent 需要的上下文文件列表

Phase 2：Execute（执行阶段）

Trellis 的核心设计：main session 不做实现，派 sub-agent 去做。

为什么？因为 sub-agent 会得到 implement.jsonl 注入的 spec 上下文，而 main session 没有。如果你在 main session 里直接写代码，等于绕过了规范注入——那你前面写的 spec 就白写了。

# main session 派 sub-agent：
# Agent type: trellis-implement
# 它会被注入 implement.jsonl 里列的所有 spec 文件
# 然后按 prd.md 实现

# 实现完后派 check agent：
# Agent type: trellis-check
# 它会被注入 check.jsonl 里的规范
# 然后审查代码、运行 lint/type-check/tests

Phase 3：Finish（收尾阶段）

# 1. 更新 spec（如果这次学到了新东西）
# 2. commit
# 3. /trellis:finish-work

我觉得最有用的一点

task 目录存一切。每次任务的所有东西——需求、调研、实现记录——都在 .trellis/tasks/MM-DD-任务名/ 下面。两周后你想知道"当时为什么这么设计"，去翻那个目录就行，不用翻聊天记录。

三、Codegraph：比 grep 聪明一百倍的代码搜索

痛点

传统的 grep / rg 搜索：

grep -r "execute_skill" app/   # 返回几百行，大部分是 import 语句

Codegraph 的做法：

> codegraph_context "execute_skill 是怎么被调用的"
# 直接返回：入口点、相关符号、调用关系图
# 而且有代码片段，但不会把整个文件 dump 给你

我常用的几个命令

我要干什么	用哪个
“这个功能是怎么实现的？”	`codegraph_context` — 一键返回入口 + 相关符号 + 关键代码
“函数 A 怎么调用到函数 B 的？”	`codegraph_trace from to` — 追踪完整调用链
“这个符号在哪定义的？”	`codegraph_search` — 只返回位置，不返回代码
“改这个函数会影响哪些地方？”	`codegraph_impact` — 反向查找所有调用者
“这个模块都有哪些函数？”	`codegraph_explore` — 展示一个区域的多个相关符号

使用心得

先 codegraph，再读文件。大部分问题 codegraph 直接能回答，不需要打开文件。只有需要逐行审查的时候才用 Read。

Codegraph 背后是一个 SQLite 知识图谱，索引了项目里每个符号、每条边、每个文件。读操作是亚毫秒级的——比 grep 快，而且给的是结构化信息不是文本匹配。

四、grill-with-docs：在写代码之前，先把话说清楚

这个 skill 干什么的

/grill-with-docs 是一个"面试式"的领域建模工具。它会：

追问你到底在说什么 — “你说的’订单’，是指用户的预订记录，还是支付后的确认单？”
挑战你的术语 — “你的 CONTEXT.md 里把 ‘取消’ 定义为 X，但你这次说的是 Y——到底是哪个？”
压力测试你的设计 — “如果用户取消了一半的订单项，你这个流程还能走通吗？”
现场更新术语表 — 每搞清楚一个概念，立刻写到 CONTEXT.md 里
必要时写 ADR — 只有满足三个条件才写：难逆转、没上下文会困惑、有真正的权衡

我的使用场景

新 feature 设计：在写 PRD 之前先 grill 一轮，把概念边界厘清
重构前：确保新旧术语对齐，别重构到一半发现理解错了
多人协作：CONTEXT.md 相当于团队的"通用语言词典"

产出物

docs/
├── CONTEXT.md          # 术语表（不含任何实现细节，纯粹的概念定义）
└── adr/
    ├── 0001-agent-first-architecture.md
    └── 0003-remove-distilled-memory.md

五、MCP：让 AI 长出"手"

什么是 MCP

Model Context Protocol — Anthropic 推的一个开放协议，让 AI 模型能调用外部工具。简单说就是：AI 不只是"说话"，还能"做事"。

我怎么用的

# config/mcp_servers.yaml
servers:
  - name: weather_api
    url: http://localhost:9000/mcp
    transport: streamable-http
  - name: internal_tools
    url: https://internal-api.example.com/mcp
    headers:
      Authorization: "Bearer ${MCP_AUTH_TOKEN}"

MCP Server 启动后，它提供的工具会自动被发现、包装成 LangChain StructuredTool、注册到 Agent 的工具列表里。Agent 在 ReAct 循环中可以像调本地工具一样调 MCP 工具。

关键经验

只支持 HTTP/StreamableHTTP，不支持 Stdio。需要本地工具的话要部署成 HTTP 服务
防御性导入：mcp 包没装的时候应用正常启动，MCP 功能降级——别让一个外部依赖挂掉整个应用
每个工具调用创建新 session，高频场景下注意连接开销

六、Agent Memory（docs/agent.md）：不只是"写文档"

我的文档哲学

大部分人的"开发文档"长这样：

2026-01-01: 修复了登录 bug
2026-01-02: 添加了用户列表页面
2026-01-03: 优化了数据库查询

这不是文档，这是 git log 的手抄版。

我的 agent.md 结构

# Agent Memory

## 当前维护方式       ← 运维约定（怎么启动、怎么部署、注意事项）
## 最近十日时间线     ← 按模块写可复用结论，不写 commit hash
## 关键模块记忆       ← 核心链路、关键文件、当前架构版本
## 已知长期风险       ← 环境坑、安全坑、业务坑
## 历史归档摘要       ← >10 天的内容合并归纳到这里

核心原则

只写可复用结论：“logs 字段直接透传原始对象数组，禁止用 _as_list_of_str”——下次 AI 读到就不会再犯
不写流水账：“构建通过”、“已推送”——删掉
覆盖优于追加：如果这次修改了已有结论，直接改原文，别在后面加"更新：XXX"
十天滚动窗口：只保留最近 10 天的详细时间线，更早的合并到归档摘要

关键规则

每次任务对话结束前，必须先更新 agent.md，再汇报完成。

这条规则写在我的 CLAUDE.md 最高优先级位置。因为 AI 会话的记忆是临时的——下次对话是全新的上下文，只有文件里的东西能跨会话传递。

为什么不用"自动文档生成"？

试过。删了。LLM 自动蒸馏产出的"记忆"质量太低——要么太泛（“优化了系统性能”），要么太碎（把一次调试的中间状态当结论写进去）。人审核 + AI 辅助写才是对的姿势。

七、我的日常开发节奏（真实流程）

以一个典型需求为例——“给 Monitor API 加认证”：

上午 10:00
  $ python .trellis/scripts/task.py create "Monitor API 认证中间件"
  → 创建 .trellis/tasks/06-04-monitor-auth/

上午 10:05
  → AI 自动进入 brainstorm 模式
  → AI: "Monitor 路由现在有多少个？我看看代码……12 个端点。
       你是想所有都保护还是留 health 端点免认证？"
  → 我: "health 免认证，其它都要"
  → AI 更新 prd.md

上午 10:15
  → AI: "认证方式你倾向哪种？
       1. API Key（简单，适合内网）
       2. JWT（灵活，但重）
       3. IP 白名单（零代码改动）"
  → 我: "API Key，环境变量配"
  → AI 记录决策到 prd.md

上午 10:30
  → AI: "需求明确了，我总结一下……"
  → 我: "ok"
  → $ python .trellis/scripts/task.py start 06-04-monitor-auth

上午 10:35
  → AI spawn trellis-implement sub-agent
  → sub-agent 被注入 implement.jsonl 里的 spec 文件
  → sub-agent: 读 prd.md → 读 spec → 写代码 → lint → type-check

上午 10:50
  → AI spawn trellis-check sub-agent
  → sub-agent: 读 check.jsonl → 审查代码 → 运行测试 → 通过

上午 11:00
  → AI: "这次新增了安全模块，需要更新 spec"
  → /trellis-update-spec → 写入 .trellis/spec/backend/security.md
  → AI: "commit 计划：1个 commit，3个文件"
  → 我: "ok"
  → commit 完成

上午 11:05
  → AI 更新 docs/agent.md（记录新模块、新风险）
  → /trellis:finish-work
  → 收工

整个过程我写了几行代码？零行。我做的事情：

描述需求
做决策（认证方式选 API Key）
确认方案
审核结果

八、几条"血泪教训"

1. "小改动"也要走流程

“就改一行代码，别建 task 了吧”——这是最大的陷阱。

一行代码改动可能：

改了 API 返回格式，前端挂了
引了一个新 import，循环依赖了
修了一个 bug，引入两个新 bug

Trellis 的 check agent 就是防这个的。除非你说 skip trellis，否则 AI 会坚持走流程——这不是教条，是血的教训。

2. Spec 不是一次写完的

第一次写 spec 的时候你不可能想全。正确的姿势是：

开发过程中发现了新约定 → 立刻 /trellis-update-spec
修了一个难查的 bug → /trellis-break-loop 分析根因 + 写进 spec
每两周翻一遍 spec，删掉过时的、合并重复的

3. 不要用 AI 的"记忆"功能替代文档

Claude Code 有 memory 机制，但它存的是"用户偏好"、"项目背景"这类跨会话的元信息。代码约定、架构决策、接口行为——写进 spec 和 agent.md，别靠 memory。

4. 工具护栏很重要

我的 Agent 有这些护栏：

重复失败检测：同一个工具连续失败 2 次 → 硬停止，别无限重试
无进展循环检测：连续 3 轮没有实质性进展 → 注入提醒
429 熔断切换：API Key 被限流 → 自动切下一个 Key，全挂了就快速失败

AI 写代码快，犯错的速速也快。护栏不是限制 AI，是保护你的系统。

5. Codegraph 要配好

Codegraph 的核心价值是"不要让 AI 用 grep 翻代码"——那又慢又费 token。配置好 .codegraph/ 索引后，AI 对代码库的"感知"从"模糊文本搜索"变成了"精确符号查询"。

九、如果你也想搭这套流程

最小可行配置

1. Claude Code（IDE 插件或 CLI）
2. CLAUDE.md（项目根目录，写清楚项目概览 + 开发命令 + 核心架构）
3. .claude/rules/（至少写 logging-style.md + known-risks.md）
4. docs/agent.md（从当前维护方式 + 关键模块记忆开始）

进阶配置

5. Codegraph（codegraph init + 后台 daemon）
6. Trellis（trellis init + 配好 spec + task 流程）
7. grill-with-docs（需要 CONTEXT.md + ADR 的时候用）
8. MCP Server（有外部工具需要 AI 调的时候配）