Intent Debt 意图债务详解

💳 通俗比喻：技术债就像信用卡欠款——你赶进度时偷了懒，代码质量欠下了债。认知债是文档没写好，新同事看不懂代码，得花时间"还债"。意图债最隐蔽——代码做了什么你知道，但为什么要这么做，没人记得了。就像你翻出三年前的一个hack，注释写着"// 不要删这行"，但你完全不知道为什么不能删。

"世界上有三种债务。第一种写在代码里，你用重构来还。第二种写在脑子里，你用文档来还。第三种写在时间里——当最初的设计意图被遗忘，你就背上了意图债务。" —— 妙趣AI

📖 Martin Fowler 的三层债务框架

2026年4月，Martin Fowler发布文章"Technical, Cognitive, and Intent Debt"，将技术债扩展为三个层次，登上了Hacker News首页（106分）。

🔴 第一层：Technical Debt（技术债）

定义：代码层面的欠债——糟糕的设计、临时的hack、缺失的测试。

症状：代码难维护、bug率高、新功能开发慢。

偿还方式：重构、补测试、改善设计。

# 技术债示例
# 临时hack：硬编码的配置值
API_URL = "https://prod-api.example.com"  # TODO: 移到配置文件

# 偿还：配置化
API_URL = config.get("api_url")

🟡 第二层：Cognitive Debt（认知债）

定义：理解层面的欠债——缺少文档、命名不清、架构图过时。

症状：新人上手慢、频繁问"这段代码什么意思"、重复犯错。

偿还方式：写文档、改善命名、画架构图。

# 认知债示例
def process(d):  # 什么d？process什么？
    x = d.get('v')  # v是什么？
    if x > 100:     # 为什么是100？
        return True

# 偿还：清晰命名+文档
def is_high_value_customer(order_data: dict) -> bool:
    """判断是否为高价值客户（订单金额 > VIP_THRESHOLD）"""
    order_amount = order_data.get('total_amount', 0)
    return order_amount > VIP_THRESHOLD

🔵 第三层：Intent Debt（意图债务）

定义：设计意图的丢失——代码还在跑，但没人知道为什么这样设计。

症状：不敢改代码（怕改错）、重构时发现"原来这样设计是有原因的"、反复踩同一类坑。

偿还方式：记录决策原因（ADR）、写设计文档、保留上下文。

# 意图债示例
# 代码能跑，但没人知道为什么这么写
def calculate_price(base, factor):
    # 为什么乘以0.97？谁决定的？
    # 有人说和2019年的一次促销有关，但不确定
    return base * factor * 0.97

# 偿还：记录意图
def calculate_price(base: float, factor: float) -> float:
    """
    计算最终价格。
    0.97系数原因：2019-Q3定价策略调整，
    为了在保持毛利的前提下提升转化率。
    详见 ADR-2019-042: 定价策略调整
    """
    return base * factor * PRICING_ADJUSTMENT_FACTOR  # 0.97

🔬 三层债务的关系

# 债务层次：越深层越隐蔽，越难偿还
#
#  ┌─────────────────────────┐
#  │   Intent Debt 意图债    │  ← 最隐蔽：为什么这么做
#  │  ┌───────────────────┐  │
#  │  │ Cognitive Debt    │  │  ← 中间层：怎么理解代码
#  │  │  ┌─────────────┐  │  │
#  │  │  │ Tech Debt   │  │  │  ← 最表层：代码质量
#  │  │  └─────────────┘  │  │
#  │  └───────────────────┘  │
#  └─────────────────────────┘
#
# 偿还顺序：Tech → Cognitive → Intent
# 但现实中往往反向积累：意图丢失 → 认知困难 → 代码腐化

⚙️ OpenClaw 实战：管理意图债务

在AI Agent系统中，意图债务有特殊含义——Agent的行为意图需要被显式记录和管理，否则人类无法理解Agent为什么做了某个决定。

1. ADR（Architecture Decision Records）

# OpenClaw MEMORY.md - 记录决策意图

## ADR-2026-04-22: 术语页面生成策略

### 决策
术语百科采用"每日5页"的稳定产出节奏

### 原因
1. 质量优先于数量，5页可以保证每页深度
2. 搜索引擎更偏好稳定更新而非爆发式发布
3. 凌晨4点执行，避开白天API高峰

### 替代方案
- 批量20页：质量下降，相似度过高
- 每日1页：产出太慢，SEO积累不足

### 后果
- 5页 × 30天 = 150页/月
- 需要持续监控质量指标

2. SOUL.md 行为意图声明

# SOUL.md - Agent行为意图显式化

intent_declarations:
  daily_cron_tasks:
    why: "自动化确定性替代人工不确定性"
    not_why: "不是为了产出而产出"
    
  seo_quality_first:
    why: "低质量页面伤害整站权重"
    not_why: "不是追求数字好看"
    
  check_even_if_not_fixing:
    why: "检查即管理，持续暴露问题"
    not_why: "不是为了报告而检查"

3. 决策日志

# memory/YYYY-MM-DD.md 中记录决策

## 2026-04-22 决策记录

### [04:00] 术语百科任务
- **选择**: 生成5个热点术语页面
- **原因**: HN热点词+行业趋势+未覆盖术语
- **未选择**: 随机选题 — 缺乏时效性
- **后续影响**: 新增页面将加入sitemap并推送索引

### [08:00] 日报生成
- **选择**: 使用Qwen3.6-27B生成日报
- **原因**: Dense Model输出更稳定一致
- **未选择**: MoE模型 — 日报需要一致性而非多样性

📊 AI Agent 系统中的意图债务

债务类型	Agent系统表现	偿还方式
技术债	Prompt冗余、工具链混乱	重构Prompt、整理工具
认知债	SOUL.md不清晰、行为不可预测	完善SOUL.md、写教程
意图债	Agent做了某事但没记录原因	ADR + 决策日志 + MEMORY.md

💡 防范意图债务的最佳实践

每个决策都记录原因 — 不仅记"做了什么"，更要记"为什么做"
使用ADR模板 — 标准化记录架构决策
定期复盘 — 回顾过去的决策，验证意图是否还成立
Agent行为审计 — OpenClaw的执行日志是天然的意图记录
SOUL.md显式声明 — 把Agent的"为什么"写进人格文件

🤖 OpenClaw：让Agent的意图可追溯

通过SOUL.md、MEMORY.md和决策日志，OpenClaw让每个Agent行为都有据可查。

查看 OpenClaw 记忆管理教程 →

Intent Debt 意图债务技术债认知债 Martin Fowler ADR OpenClaw