今天不只是
学一个工具

过去：把 AI 当聊天框

现在：把 AI 放进任务系统

Agent 不只回答问题。它可以读文件、写文件、调用工具、执行命令，并把结果留在项目里。

VS Code：项目工作台

Project/
├── CLAUDE.md
├── .claude/
│   ├── rules/
│   ├── skills/
│   ├── agents/
│   └── settings.json
├── docs/
│   └── ai/
└── src/

真实项目里，不需要把所有计划文件都放在根目录。根目录放入口说明，细分规则、能力和运行手册进入对应目录。

Git：给 Agent 工作加上回滚能力

$ git diff
- 旧标题
+ 新标题

$ git status
modified: src/app.ts
new file: docs/ai/release-runbook.md

Agent 会改文件。Git 让这些改动可比较、可撤回、可提交。

• 开始前看状态
• 修改后看 diff
• 满意后再 commit

终端：Agent 的手

$ pnpm test
$ npm run build
$ rg "TODO"
$ git diff --stat

终端让 Agent 能运行命令、检查结果、自动化重复任务。

Windows 为什么推荐 WSL2

很多 CLI Agent 和开发工具默认面向类 Linux 环境。WSL2 可以减少路径、权限、命令兼容问题。

CLI、订阅、API、网络

• 订阅和 API：决定能不能使用服务
• 网络：决定连接稳定性
• CLI / IDE：决定交互入口

项目上下文与工具调用

上下文告诉 Agent “这里发生了什么”；工具让 Agent “真的能做什么”。

Agent 可以执行，但人仍然负责

AI 输出不是自动正确。它能提高执行速度，但不能替代人对目标、事实和风险的判断。

• 关键文件要看 diff
• 重要事实要核查来源
• 敏感命令要保留确认

Harness：把模型接进工作系统

• 状态：项目文件、规则和历史决策让下一步有上下文。
• 动作：Shell、Git、编辑器和外部工具把回答变成可执行操作。
• 边界：权限、hooks、tests、CI 让执行可控、可回退。
• 复用：skills、commands、agents 把稳定流程沉淀下来。

上下文组件：项目不是普通文件夹

Project/
├── CLAUDE.md
├── .claude/
│   ├── rules/
│   │   ├── core.md
│   │   ├── config.md
│   │   └── release.md
│   ├── skills/
│   ├── agents/
│   └── settings.json
└── docs/
    └── ai/
        ├── architecture.md
        └── release-runbook.md

上下文不是把所有 Markdown 堆在根目录。更稳的做法是：入口文件指路，规则分层，能力归档，长期知识进入 docs/ai。

CLAUDE.md / AGENTS.md：项目入口说明

入口文件不需要塞满所有规则。它应该说明项目目标、读文件顺序、关键目录和不能越界的事项。

• 先读哪些规则
• 哪些目录是长期上下文
• 哪些动作必须先确认
• 完成前如何验证

.claude/rules：把长期规则拆开

# CLAUDE.md

Read these before editing:
- .claude/rules/core.md
- .claude/rules/config.md
- .claude/rules/release.md
- docs/ai/architecture.md

Before finishing:
- summarize changed files
- list verification performed
- record open questions

docs/ai：把架构和 runbook 留下来

docs/
└── ai/
    ├── architecture.md
    └── release-runbook.md

.claude/rules/
├── core.md
├── config.md
└── release.md

文件名只是参考，不必照抄。真正要学的是：把长期上下文、临时计划、执行记录分层放置，让 Agent 每次进入项目都能沿着同一套流程工作。

• docs/ai：适合放架构、runbook、长期说明
• .claude/rules：适合放稳定行为规则
• 也可以像 superpowers skills 一样分 specs/ 与 plans/

Tools / Shell / Git：Agent 的行动层

规则只决定“怎么做”，工具才让 Agent 真正读文件、改文件、跑命令、查状态。

.claude/skills：沉淀高频流程

.claude/
└── skills/
    ├── runtime-diagnosis/
    ├── config-migration/
    ├── release-check/
    └── incident-triage/

Handoff：让任务跨会话延续

# Handoff

## Current Goal

## Current State

## Files Changed

## Verification

## Open Questions

## Next Step

Handoff 不一定放在根目录。更真实的做法是把长期运行手册放进 docs/ai，把临时交接放进当前 issue、PR 或任务记录。

grill：先追问，不急着生成

需求不清时，让 AI 先问问题。追问不是拖延，而是在降低返工。

plan：先规划，不急着改文件

请先不要修改文件。

请阅读 CLAUDE.md / AGENTS.md、.claude/rules 和现有目录，输出：
1. 你理解的目标
2. 计划步骤
3. 可能风险
4. 预计会创建或修改的文件
5. 需要我确认的问题

计划让人类能提前纠偏。尤其是 Agent 会写文件时，先 plan 再 execute 更可控。

verify：验证结果

验证可以是 tests，也可以是 checklist、review、事实核查。

handoff：沉淀交接

本轮完成：
- 更新 docs/ai/architecture.md
- 补充 .claude/rules/release.md

仍需确认：
- 发布检查项是否完整

下一步：
1. 运行 smoke test
2. 补充 release-runbook.md

长任务不应该只停在“我完成了”。要留下下一轮能接上的状态。

演示步骤：准备项目文件夹

learning-wiki/
├─ sources.md
├─ CLAUDE.md
└─ docs/
   └─ ai/

演示项目可以更小，但仍遵守同一原则：入口文件说明规则，资料可追踪，长期产物进 docs/ai。

• 规则文件先短后长
• 资料来源先可追踪
• 产物目录先保持简单

演示步骤：让 Agent 规划

请阅读 sources.md 和 CLAUDE.md。

先不要写文件。请输出：
- 资料类型概览
- 建议的 Wiki 目录结构
- 第一轮最小任务清单
- 需要我确认的问题

先规划，教师现场确认后再允许小步执行。

演示步骤：执行、验证、交接

生成初始产物后，用 checklist 检查，再生成 handoff。

• 有没有覆盖 sources.md？
• 目录是否符合规则？
• handoff 能否让下一轮继续？