清风自叙小筑

Appearance

工具系统与工程化 ​

Claude Code 内置了一套原生工具组织体系——Read、Write、Bash、Grep、Glob、Edit、Agent……这些工具和 Agentic Harness 共同构成了工程化的基础设施。

Agentic Loop——工具驱动的智能循环 ​

alt text

Claude Code 的工作循环——Agentic Loop 可以分为三个阶段，根据任务需要灵活切换。

alt text

alt text

Claude（模型）负责推理，Tools 负责行动。而 Claude Code 扮演的角色是 Agentic Harness，它把模型和工具连接起来，提供执行环境、上下文管理、权限控制等基础设施。

alt text

从原语到涌现——工具设计哲学 ​

五种原子操作 alt text

alt text

alt text

简单工具+智能组合=无限可能

权限控制体系 ​

Claude Code 并不是简单地“给或不给权限”，而是构建了一套分层的权限控制体系：既保证低风险操作的流畅执行，又对高风险行为进行精细约束，从而在效率与安全之间取得平衡。

alt text

alt text

alt text

结构化输入输出（MCP 返回结构化数据，不需要解析文本）、工具发现（连接一个 MCP Server，所有工具自动可用）、安全隔离（MCP 在 Server 端做访问控制，比 Bash(curl *) 精细得多）。这些正是上一讲（第 17 讲）详细讲解的内容。 alt text

alt text

工程化进阶 ​

handless 软件工程中有大量任务天然不需要实时对话。CI/CD 流水线在每次提交时自动运行，Pre-commit Hook 在提交前自动检查，定时任务在每天凌晨自动生成报告。这些场景需要的是非交互模式，也就是 Headless 模式。

alt text

Rules 规则系统深度剖析 ​

Claude Code 中的“规则”分布在两个完全不同的层面： ​

alt text

# 项目概述
全栈 TypeScript 项目。前端 React 18 + Tailwind，后端 Express + Prisma + PostgreSQL。

# 命令
- `pnpm dev` — 启动前后端开发服务器
- `pnpm test` — 运行全部测试
- `pnpm lint` — ESLint + Prettier 检查
- `pnpm db:migrate` — 执行数据库迁移

# 核心约定
- 包管理器用 pnpm，不用 npm 或 yarn
- commit message 用 conventional commits 格式
- 所有 API 返回 { success: boolean, data?: T, error?: string }
- 环境变量通过 .env 管理，不硬编码

# 详细规范
领域规范见 .claude/rules/ 目录，按文件类型自动加载。

Agent SDK ​

alt text

alt text

alt text

alt text

第一大卡点，AI 的行为不可预测 点，那实际上这个问题的解法就是说我们现在要对 AI 的这个工程进行约束，这个就是我觉得是 Claude Code 工程化实战解决的最大的问题，就是我们如何通过理解工程的结构，通过这些东西去给Claude声明边界，去约束它.

未来的程序开发模式，也将转向规范式开发。核心逻辑在于撰写清晰完备的 SPEC，只要规范文档足够精准、足够细致，AI就能严格依照规范执行任务；后续还有监管问题，需要 Hooks 做检查，这都是我们要贯通的能力。

第二大卡点，是AI能力无法复用。日常应用中往往存在这类痛点：今天为 AI 设定的指令与逻辑，隔天需要重新配置；换一个应用场景，就要重新搭建逻辑；团队内部更是缺乏统一标准，不同成员使用 AI 的方法、配置的逻辑各不相同，新员工接手又要重新摸索，导致大量重复劳动，效率极低。

针对这一问题，我们需要建立一套标准化、可复用的技能体系与方法论，将AI的核心技能、执行逻辑沉淀为通用模块，实现一次配置、多场景复用、跨团队共享，彻底打破能力复用壁垒。当然，这套体系并非简单的复制粘贴，需要结合具体项目场景灵活适配，这也是我们需要掌握的核心贯通能力。

第三大卡点，是复杂任务处理易陷入混乱。AI应对单一、简单任务时表现稳定，可一旦面对多环节、高复杂度的综合任务，就容易出现逻辑混乱、上下文混淆、执行偏差的问题。

对应的解决方案，是搭建子智能体（Subagent）体系，通过专业化分工实现任务拆解与上下文隔离，让专属智能体负责对应细分任务。需要明确的是，子智能体并非比主智能体更“聪明”，核心作用是划分清晰的任务边界与职责区间，让每个智能体专注于单一模块工作，避免多任务混杂导致的逻辑紊乱，保障复杂任务有序推进、高效落地。

alt text

Harness 架构 ​

翻译一下，Claude Code 是一个智能体编排框架，包裹在 Claude 模型外面。它提供工具、上下文管理和执行环境，把一个语言模型变成一个有能力的编码 Agent。

工具、上下文管理、执行环境

alt text

Agent Harness = 包裹 LLM 的运行时基础设施，管理工具调度、上下文工程、安全执行、状态持久化和会话连续性。LLM 只负责推理决策。

alt text

  • Tools（工具），模型的手脚。Read、Write、Edit、Bash、Grep……这些工具赋予模型与文件系统、终端、网络交互的能力。没有工具，模型只能说，不能做。
  • Context（上下文），模型的记忆加载器。CLAUDE.md、系统提示词、对话历史、工具定义——这些上下文在每一轮循环中被注入模型，决定了模型看到什么、知道什么。上下文管理的精妙之处是，它不仅是被动的信息传递，还包括主动的压缩和重注入策略。
  • Memory（记忆），模型的长期存储。跨会话的记忆持久化，让模型能“记住”你的偏好、项目规则和历史决策。CLAUDE.md 是显式记忆，自动记忆（~/.claude/memory/）是隐式记忆。没有 Memory，每次对话都从零开始。
  • Hooks（钩子），模型的神经反射。事件驱动的自动化机制，在工具执行前后触发自定义逻辑。比如每次保存文件前自动格式化，每次提交前自动运行 lint。Hooks 让 Harness 有了“条件反射”的能力——不需要模型主动决策，某些行为会自动发生。
  • Permissions（权限）——模型的安全围栏。哪些工具可以自由使用，哪些需要人工审批，哪些完全禁止——权限系统是 Harness 的安全底线。它解决了一个核心矛盾：你希望 Agent 足够自主以提高效率，但又不希望它自主到失控。

alt text

  • 模型主动停止——Claude 认为任务完成，生成纯文本回复，不再请求工具调用。API 返回 stop_reason: "end_turn"。

  • 达到最大轮次——Harness 设置了 --max-turns 限制，防止无限循环。

  • alt text

对话历史（180K tokens）
    │
    ▼ 压缩触发
┌────────────────────────────┐
│ 保留：最近的消息（完整）      │
│ 压缩：早期消息 → 摘要        │
│ 重注入：CLAUDE.md 内容       │
│ 重注入：系统提示词            │
│ 重注入：工具定义              │
└────────────────────────────┘
    │
    ▼
压缩后对话历史（~80K tokens）
    │
    ▼ 继续工作

alt text

alt text

alt text

目录文件清单 ​

📁 00 nodejs+next.js/claude code/
├── 📄 1 claude 基础.md                     # 主笔记（46 KB）
├── 🖼️ 1.png ~ 6.png                        # 6 张早期截图
├── 🖼️ image.png                            # 1 张根目录图
├── 🖼️ image-1.png ~ image-83.png           # 83 张正文插图
└── 总计：1 个 Markdown + 90 张图片