搭建项目骨架与工作目录

搭一个干净的工作目录

上一节我们写了 AGENTS.md。现在把 md-tools 的项目骨架立起来。做项目别在乱七八糟的目录里瞎搞，专门建一个：

cd ~
mkdir -p md-tools
cd md-tools
pwd    # 确认在 md-tools

---

把需求写成文件，再说给 Pi 听

和用其他工具一样，先把需求写成文件，再让 Pi 读。这样需求有据可查、改起来方便。

建 README.md 描述 md-tools 的完整需求：

# md-tools — Markdown 文档处理工具箱

一个在命令行里处理 Markdown 文件的小工具，命令如下：
- `node index.js stats <文件>`       统计文件字数、段落数、标题数
- `node index.js convert <文件>`     把 .md 转成纯文本输出
- `node index.js rename <文件>`      把文件名中的空格改成 -（下划线转连字符）

要求：
1. 每个操作先打印「将做什么」，确认后才真正执行
2. 文件不存在时给出清晰提示，而不是报错
3. 用 Node.js 标准库即可，不引入外部依赖

这就是给 Pi 的「需求文档」。把话说清楚，它才能做对。

---

初始化项目

两种方式都可以：

• 自己：npm init -y 生成基础 package.json
• 交给 Pi：进 pi，说「帮我初始化这个 Node.js 项目」

本课建议自己先 npm init -y，把底子立起来，再看 Pi 怎么接手。

npm init -y

---

检查这节的成果

这一节结束，你应该有：

md-tools/
  AGENTS.md      # 项目约定（上一节写的）
  README.md      # 需求说明
  package.json   # 项目骨架

---

落地练习：让 Pi 复述需求

在 md-tools 里启动 pi，说：

读一下 README.md 和 AGENTS.md，然后告诉我：这个工具要实现哪几个命令？

观察它是否先读文件，再准确复述出 stats/convert/rename 三个命令。

怎么判断做对了？——Pi 先读文件（看消息区的工具轨迹），再准确说出三个命令和各自作用，说明它「入戏」了。

卡住了怎么办？ 它没读文件就开始说 → 打断「先读 README.md 和 AGENTS.md」。它复述不全 → 回去把 README 的命令列表写得更明确。

---

常见坑：跳过需求文档直接开干

最省事也最坑的做法，是心里有个大概，直接让 Pi「写个 markdown 工具」。

结果它按自己理解的来，做出来才发现「我要命令行工具，它给我做了个别的东西」。

先花几分钟把需求写成 README，再让 Pi 读，能省掉大量返工。需求文档是「你描述」这个环节最重要的载体。

---

小结

1. 建独立工作目录 md-tools
2. 先把需求写成 README，再让 Pi 读
3. 自己 npm init -y 打好骨架
4. 需求写清楚，后面少返工
5. 我们已备好 AGENTS.md + README + package.json

下一节，让 Pi 动手实现，走完整个闭环。