给 AI 装上工程化中间层：一套五层 Claude Code Harness 的设计图解

flowchart LR
    M["AI 模型<br/>(通用能力强)"]
    GAP["缺少中间层<br/>约束/工具/反馈/记忆 都对不上"]
    P["真实项目<br/>(有架构与硬约束)"]
    M -- "按通用习惯写" --> GAP
    GAP -- "撞墙：方向对、细节失控" --> P

    M2["AI 模型"]
    H["Harness<br/>工程化中间层"]
    P2["真实项目"]
    M2 --> H --> P2
    H -. "① 精确投喂约束" .-> M2
    H -. "② 接入够不着的工具" .-> M2
    H -. "③ 建自动反馈环" .-> M2
    H -. "④ 沉淀跨会话教训" .-> M2

flowchart TB
    subgraph L5["① 进化层 Evolution —— Harness 自己如何改进?"]
        direction LR
        E1["/learn 沉淀经验"]
        E2["/gc 健康度扫描"]
        E3["pitfalls.md 错误记忆"]
        E4["evals/ 行为回归"]
    end
    subgraph L4["② 编排层 Orchestration —— 怎么组织执行?"]
        direction LR
        O1["/dev 统一入口"]
        O2["PRP 四阶段"]
        O3["/new-agent · /add-memory"]
    end
    subgraph L3["③ 策略层 Policy —— 什么必须 / 禁止做?"]
        direction LR
        P1["CLAUDE.md 硬红线"]
        P2[".claude/rules 5 条 (glob 注入)"]
        P3["project-lint 数据驱动"]
        P4["6 个 Hook · code-reviewer"]
    end
    subgraph L2["④ 知识层 Knowledge —— Agent 知道什么?"]
        direction LR
        K1["CLAUDE.md (全局)"]
        K2["ai-docs 模块三件套"]
        K3["catalog · pitfalls"]
        K4["渐进加载 L1→L3"]
    end
    subgraph L1["⑤ 能力层 Capability —— Agent 能做什么?"]
        direction LR
        C1["run-graph 起 LangGraph"]
        C2["db-shell 查 PG/Neo4j/Redis"]
        C3["复用全局 lark-* / memory"]
    end

    L5 --> L4 --> L3 --> L2 --> L1
    L1 -. "数据流：上层调下层，不可反向依赖" .-> L5

flowchart LR
    subgraph HARNESS["Harness 五层 (工具/脚手架)"]
        direction TB
        h1["进化层"] --> h2["编排层"] --> h3["策略层"] --> h4["知识层"] --> h5["能力层"]
    end

    subgraph TARGET["目标系统三层 (被生产的产品 src/)"]
        direction TB
        t1["编排层 orchestration/agents<br/>LangGraph Supervisor + Worker"]
        t2["记忆层 memory<br/>Zep / Mem0 / Graphiti 封装"]
        t3["存储层 storage<br/>Postgres / Neo4j / Redis"]
        t1 -- "只能调下层" --> t2 -- "只能调下层" --> t3
    end

    HARNESS == "脚手架 / 约束 / 验证" ==> TARGET

flowchart TB
    Start(["会话/操作发生"]) --> L1
    L1["L1 全局 · 会话启动<br/>加载 CLAUDE.md：硬红线 + 路由 + 入口"] --> Edit{"开始操作某文件?"}
    Edit -- "匹配到 glob" --> L2["L2 模式匹配<br/>.claude/rules/* 按 glob 自动注入<br/>(编辑 .py → python-code；src/memory/** → memory-rules)"]
    Edit -- "要编辑具体模块" --> L3["L3 模块级<br/>读 ai-docs/docs/modules/&lt;模块&gt;/ 三件套<br/>guide(必读) / external-api / extension"]
    L2 --> Work(["带着刚好够用的上下文干活"])
    L3 --> Work
    Edit -- "不确定去哪查" --> Cat["查 catalog.md 总目录<br/>或 pitfalls.md 踩过的坑"] --> Work

sequenceDiagram
    autonumber
    participant U as 用户/Agent
    participant CC as Claude Code
    participant HK as Hook 体系 (_run.sh 守卫)

    Note over CC,HK: 会话开始
    CC->>HK: SessionStart
    HK-->>CC: conda-env-check.sh 轮询 conda 环境是否就绪

    Note over CC,HK: Agent 准备编辑某文件
    CC->>HK: PreToolUse (Edit/Write)
    HK-->>CC: knowledge-routing.py 注入「该读哪些规则/模块文档」(每文件每会话一次)

    Note over CC,HK: Agent 写入文件后
    CC->>HK: PostToolUse (Edit/Write)
    HK-->>CC: post-edit.sh 自动 ruff/prettier 格式化
    HK-->>CC: lint.py 项目语义检查 —— 违规则 exit 2 反馈 Agent 自纠
    HK-->>CC: doom-loop-detect.py 同文件编辑计数，第 5 次起预警

    Note over CC,HK: 任务收尾 / 上下文压缩
    CC->>HK: Stop
    HK-->>CC: stop-check.py 残留 breakpoint()/高频编辑提醒 (不阻断)
    CC->>HK: PreCompact
    HK-->>CC: precompact-save.py 保存 git 工作态，压缩后可恢复

flowchart TB
    F(["编辑后 PostToolUse 喂入文件路径"]) --> PY{"是 .py 文件?"}
    PY -- 否 --> OK0(["静默 exit 0"])
    PY -- 是 --> R{"逐条规则"}
    R --> S1{"① path_contains / file_context<br/>文件级前置条件命中?"}
    S1 -- 不满足 --> SKIP["跳过整条规则"]
    S1 -- 满足 --> S2{"② pattern<br/>行级主正则命中?"}
    S2 -- 否 --> NEXT["看下一行/下一条"]
    S2 -- 是 --> S3{"③ exclude_patterns<br/>命中合法写法?"}
    S3 -- 命中 --> NEXT
    S3 -- 未命中 --> S4{"④ confirm_patterns<br/>需二次确认且命中?"}
    S4 -- 不满足 --> NEXT
    S4 -- 满足 --> V["记一条违规<br/>行号 + 原因 + fix + ref"]
    V --> OUT{"有违规?"}
    NEXT --> OUT
    SKIP --> OUT
    OUT -- 有 --> E2(["打印到 stderr，exit 2<br/>反馈 Agent 自我纠正"])
    OUT -- 无 --> OK(["静默 exit 0"])

flowchart TB
    Dev["/dev <任务>"] --> Load["加载上下文：CLAUDE.md + 触及模块的 guide + 扫一眼 pitfalls"]
    Load --> Judge{"判定复杂度"}
    Judge -- "简单<br/>单文件·改动明确·低风险" --> Direct["直接做<br/>完事跑测试 + lint"]
    Judge -- "中等<br/>多文件·需先想清楚" --> Plan["Plan 模式<br/>先列方案，确认后实现"]
    Judge -- "复杂<br/>新功能/跨模块·需可追溯" --> PRP

    subgraph PRP["PRP 四阶段 (产物落 PRP/&lt;feature&gt;/，可版本控制·可审·可验)"]
        direction LR
        S1["/refine-prd<br/>模糊需求 → 结构化 PRD"] --> S2["/generate-prp<br/>生成 PRP<br/>(强制读模块文档+pitfalls+规则)"]
        S2 --> S3["/validate-prp<br/>执行前逐项校验清单"]
        S3 --> S4["/execute-prp<br/>执行 + 跑测试 + 沉淀文档与教训"]
    end

    Direct --> Done(["完成：接口变了就 /generate-doc sync；有新教训就 /learn"])
    Plan --> Done
    PRP --> Done

flowchart TB
    L["/learn 提炼教训<br/>(现象 + 根因 + 正确做法)"] --> T{"教训属于哪类?"}
    T -- "高频·可正则检测的违规" --> P1["① 程序化：加一条 project-lint 规则<br/>(改 rules.json，跑样例验证正报/反不误报)"]
    T -- "项目层面的坑" --> P2["② 文档：pitfalls.md 追加一条"]
    T -- "用户偏好 / 项目动态" --> P3["③ 记忆：全局 ~/.claude/.../memory/"]
    T -- "模块知识更新" --> P4["对应模块三件套 / generate-doc sync"]

    P1 -. "优先级：程序化 > 文档 > 记忆" .-> P2
    P2 -. "越靠前越能「机制大于自觉」" .-> P3

flowchart TB
    A(["/dev: 给记忆层加一个写入方法"]) --> B["编排层：判定复杂度 → 走 Plan / PRP"]
    B --> C["PreToolUse 触发 knowledge-routing.py<br/>注入 memory-module-guide + memory-rules"]
    C --> D["知识层：Agent 读到「写入必须在任务完成节点 + 显式 scope」"]
    D --> E["Agent 写入文件 (能力层工具)"]
    E --> F["PostToolUse：post-edit 格式化 → lint.py 检查"]
    F --> G{"记忆 write 缺 scope?<br/>Agent 直连 Neo4j?"}
    G -- "命中违规" --> H["lint exit 2：行号+fix+ref 反馈"] --> E
    G -- "干净" --> I["doom-loop 计数 (反复试错才预警)"]
    I --> J["复杂改动：code-reviewer 子代理宏观审查<br/>记忆时机 / 层越界 / 节点契约"]
    J --> K["Stop：stop-check 收尾 (残留断点?)"]
    K --> L["有新教训 → /learn 沉淀 → 升级 lint 规则 / pitfalls"]
    L --> M(["下次同类坑被机制挡在门外"])