← Back to blog

构建可长期运行的 AI 编程代理系统（Claude Code 实战方法论）

December 8, 2025
15 min read
AIClaudeAgentEngineeringWorkflowAutomationDevOpsTypeScriptNode.js

📖 目录

  1. 核心思想：AI 没有长期记忆，系统才有
  2. Claude Code 工程级初始化模板
  3. 标准启动 Prompt（可跨 Session 继承）
  4. Rules：不是文档，是"宪法级约束"
  5. Specs：结构契约层（防止 AI 幻觉）
  6. 自定义命令集的真实定位
  7. 反复 Kill 端口的根因与彻底解决方案
  8. progress 太长的结构性风险
  9. 插入任务的工程规范
  10. 分卷（05、06...）的正确触发方式
  11. 最终结论

参考与启发：Anthropic《Effective Harnesses for Long-Running Agents》
https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents

本文基于我在真实项目中的完整实践，总结一套工程级、可跨多次 Context Window 持续推进的 AI 编程代理体系。个人感觉不算是 Prompt 工程，而是一整套：
文件系统记忆 + Git 历史 + 规则治理 + 规格约束 + 进度分卷的"AI 软件工程运维体系"。

1️⃣ 核心思想：AI 没有长期记忆，系统才有

Anthropic 文章的核心观点可以归结为一句话：

❗ Agent 永远活在"当下窗口"，长期状态必须下沉到"外部系统"。

Claude 等模型存在三个根本限制：

  1. Context Window 有上限
  2. 每个 Session 天然"失忆"
  3. 压缩（Compaction）会丢失细节与意图

如果你试图让模型"自己记得"：

  • 项目背景
  • 当前进度
  • 架构约束
  • 已完成工作

最终必然出现：

  • ❌ 重写系统
  • ❌ 假完成
  • ❌ 架构漂移
  • ❌ 功能回退
  • ❌ Git 历史污染

✅ 正确做法只有一条：

把所有"长期记忆"强制写入：文件系统 + Git + 结构化工件，而不是放在模型脑子里。

也正是 Anthropic 文中提到的：

  • Initializer Agent：建立"世界观"
  • Coding Agent：每次只做一小步，并留下可交接的痕迹

2️⃣ Claude Code 工程级初始化模板

目前总结出的标准目录结构是（后面随着开发进行可能继续优化）：

bash
1project/
2├── backend/                 # NestJS 后端
3├── frontend/                # Next.js 前端
4├── docker-compose.yml       # Postgres / Redis / Qdrant
5├── init.sh                  # 统一启动脚本
6├── PROJECT_CONTEXT.md       # 全局世界观
7├── feature_list.json        # 功能唯一真源
8├── claude-progress/
9│   ├── current.md           # ✅ 唯一可写进度文件
10│   ├── progress-001.md      # 冻结历史卷
11│   ├── progress-002.md
12│   └── progress-003.md
13└── .claude/
14    ├── project_rules.md     # 代理行为宪法
15    └── specs/               # 规格约束层（API / DB / Pipeline）

init.sh 的真实职责

bash
1#!/usr/bin/env bash
2
3echo "Starting development environment..."
4
5docker compose up -d
6
7npm install --prefix backend
8npm run start:dev --prefix backend &
9
10npm install --prefix frontend
11npm run dev --prefix frontend &
12
13echo "Environment ready."

它的作用不是"方便启动"，而是：

  • ✅ 保证每一轮 Session 的 环境一致性
  • ✅ 消灭"我这里能跑，你那里不能跑"的 AI 乱象
  • ✅ 禁止 Claude 私自切端口、杀进程、改架构

3️⃣ 标准启动 Prompt（可跨 Session 继承）

这是我现在实际使用的 标准 Coding Agent 启动 Prompt：

text
1You are the Coding Agent for this project.
2
31. Read:
4   - PROJECT_CONTEXT.md
5   - .claude/project_rules.md
6   - claude-progress/current.md
7   - feature_list.json
8   - all files under .claude/specs/
9
102. Run:
11   - pwd
12   - bash init.sh
13
143. Run only basic sanity checks (NO regression testing)
15
164. Select the next feature where "passes": false
17
185. Implement exactly one feature
19
206. Append progress to claude-progress/current.md
21
227. Commit changes

这个 Prompt 的关键不是语法，而是：

✅ 强制 Agent 每次"重新投胎之前"，先完整加载现实世界状态。

4️⃣ Rules：不是文档，是"宪法级约束"

你当前的 Rules 属于生产级 AI 治理规则，例如以下这些都是"硬约束"：

  • 只能改一个 feature
  • 不得重写架构
  • 不得杀端口
  • 不得乱改依赖
  • 不得修改 feature_list 内容结构
  • 只能写 current.md
  • 不得写历史卷

Rules 的本质不是指导，而是：

✅ 当模型"想偷懒、想发散、想重构、想自作聪明"时，把它关回笼子里。

5️⃣ Specs：结构契约层（防止 AI 幻觉）

.claude/specs/ 存在的根本意义是：

  • Rules 约束"行为"
  • Specs 约束"结构"

例如你应该有：

  • db.md：数据库表结构、索引、外键
  • api.md：接口路径、参数、返回结构
  • pipeline.md：Embedding → Qdrant → Search 流程

没有 Specs 时，AI 会出现：

  • ❌ 自己设计新数据库
  • ❌ 自己改 API 语义
  • ❌ 自己发明新系统

6️⃣ 自定义命令集的真实定位

我设计的命令如：

text
1>>start 18
2>>continue
3>>status
4>>repair

它们不是 CLI 命令，而是：

✅ "工作流宏指令（Workflow Macro）"

本质是：

  • 用一句话替代 500 token 的重复指令
  • 由规则自动展开完整流程

7️⃣ 反复 Kill 端口的根因与彻底解决方案

错误链路：

  1. Agent 启动服务
  2. 端口已被占用
  3. Agent 开始扫描进程
  4. Agent 杀死进程
  5. Agent 换端口
  6. Token 被疯狂消耗

✅ 真实解决方案不是"优化 init.sh"，而是：

每天开发结束之后我会手动执行：

bash
1./scripts/stop-dev.sh
bash
1#!/usr/bin/env bash
2
3pkill -f "next dev"
4pkill -f "nest start"
5docker compose down

下一次再进行开发时：

  • 端口是干净的
  • Claude 不需要 kill
  • Token 不再燃烧

8️⃣ progress 太长的结构性风险

当：

  • current.md 超过 800 行
  • Claude 读取成本急速上升

必须分卷：

bash
1claude-progress/
2├── current.md
3├── progress-001.md
4├── progress-002.md
5├── progress-003.md

现在采用的是：

✅ "单写 current + 手动归档"模式（最安全）

9️⃣ 插入任务的工程规范

现在正确的插入方式只有三种：

场景 做法

后续开发 加到 feature_list 末尾 马上执行 插到下一个 passes=false 前 临时插队 只用 Prompt，不改队列

绝对禁止：

  • 大规模重排 feature_list
  • AI 自动填充未来功能

🔟 分卷（05、06...）的正确触发方式

分卷不是自动行为，而是：

✅ 我授权 → Agent 执行 → 新卷冻结

标准触发 Prompt：

text
1Perform a rolling archive:
2
3- Create claude-progress/progress-005.md
4- Move the oldest half of entries from current.md into progress-005.md
5- Keep only the most recent sessions in current.md
6- Do NOT modify existing archive files
7
8After completion:
9- Confirm progress-005.md is frozen
10- Confirm current.md is the ONLY writable file
11- Commit with:
12  "chore(progress): create progress-005 rolling archive"

✅ 最终结论

长期运行 AI Agent 的本质不是"更强的模型"，而是：

  • ✅ 状态外置（File System）
  • ✅ 变更可追溯（Git）
  • ✅ 行为可治理（Rules）
  • ✅ 结构可约束（Specs）
  • ✅ 进度可压缩（Progress Volume）

当这些成立之后：

✅ AI 才第一次具备"工程级生产力"，而不是"一次性助手"。

📌 本文不是理论设计，而是我真实项目中已经跑通的 AI 工程运维方法论。

参考资源

下一步行动：尝试在您的项目中应用这些方法论，构建真正可长期运行的 AI 编程代理系统。

目录

正在生成目录...