技术图书写作专家 (Tech Blogger Agent) Skill

技术图书写作专家 (Tech Blogger Agent)

🎯 垂直职责

单一职责: 基于三层Prompt架构，系统化生成《AI Context Engineer 视角下的现代编译器实战》技术书籍章节内容。

📚 三层Prompt架构 (Three-Layer Prompt Architecture)

第1层：系统级提示词 (SYSTEM_PROMPT.md)

位置: book/SYSTEM_PROMPT.md 作用: 定义技术写作代理的角色、写作原则、结构要求 核心内容:

角色设定: 高级技术写作专家 + 编译器工程师 + AI 工程师
写作原则: 双线叙事（人类工程师线 + AI协作线）
目标读者: 1–5年Java工程师，有AI编程助手使用经验
技术栈约束: Java 21, ANTLR4 4.13.2, Maven 3.8+, JUnit 5
硬性要求: 每章必须包含6个强制小节（概述→动机→技术→AI→练习→小结）

第2层：章节级模板 (CHAPTER_TEMPLATE.md)

位置: book/CHAPTER_TEMPLATE.md 作用: 提供完整的章节结构模板，包含所有占位符 核心结构:

章节写作任务
本章基本信息（标题、模块、读者、EP范围等）
内容结构要求（6个强制小节）
章节内容检查清单（作者自检）

关键占位符:

{chapter_title} - 章节标题
{module_title} - 模块标题
{target_reader} - 读者特征
{prerequisites} - 前置知识
{ep_range} - 对应EP范围
{previous_chapters} - 前一章
{next_chapters} - 后一章
{learning_goal_1/2/3} - 学习目标

第3层：章节实例提示词 (CHAPTER_PROMPT_EXAMPLES.md & assets/prompts/)

位置:

book/CHAPTER_PROMPT_EXAMPLES.md - 示例章节提示词（第1章、第12章）
book/assets/prompts/chapterXX_prompt.md - 各章具体提示词

作用: 填充占位符后得到的具体章节Prompt，可直接发送给技术写作代理

🔗 关系图

→ ep-navigator (识别EP范围和技术上下文) → compiler-dev (理解编译器技术细节) ← document-writer (实际执行章节内容生成)

📖 书籍结构概览

5大模块，21个章节

模块 1: 基础语言与解释器 (EP1–EP12) - 第1-5章
模块 2: 从解释到编译 (EP13–EP16) - 第6-9章  
模块 3: 现代编译器架构 (EP17–EP18R) - 第10-12章
模块 4: 中间表示与优化 (EP19–EP20) - 第13-16章
模块 5: 高级优化与AI协作 (EP21) - 第17-20章

双线叙事要求

人类工程师线:

正常编译器构造实践（概念 + 代码 + 实验）
从基础解析器到研究级优化的完整路径

AI协作线:

如何设计上下文（Context），让AI安全、高效地参与
Prompt模板、验证策略、回滚方案
AI应该做/不该做的明确边界

🚀 快速工作流

方法1：使用现有章节提示词（推荐）

# 1. 查看所有可用章节提示词
ls book/assets/prompts/

# 2. 阅读第N章提示词
cat book/assets/prompts/chapter02_prompt.md

# 3. 组合系统提示词 + 章节提示词
cat book/SYSTEM_PROMPT.md book/assets/prompts/chapter02_prompt.md > chapter02_full.md

# 4. 发送给技术写作代理（document-writer）
# 将chapter02_full.md内容发送给document-writer agent

方法2：创建新章节提示词

# 1. 复制章节模板
cp book/CHAPTER_TEMPLATE.md book/assets/prompts/chapterXX_prompt.md

# 2. 填充占位符（参考BOOK_IMPLEMENTATION_PLAN.md）
vim book/assets/prompts/chapterXX_prompt.md

# 3. 填充示例：
# {chapter_title}: 第2章：表达式、运算与解释器基础
# {module_title}: 模块 1：基础语言与解释器（EP1–EP12）
# {target_reader}: 会Java、有Maven使用经验...
# {prerequisites}: Java基础语法、命令行、基本Git操作
# {ep_range}: EP3–EP4（表达式求值、访问者模式、变量内存）
# {previous_chapters}: 第1章：为人和AI搭建最小工作台
# {next_chapters}: 第3章：语句与控制流
# {learning_goal_1}: 理解表达式求值的核心机制
# {learning_goal_2}: 掌握访问者模式的设计和应用
# {learning_goal_3}: 能够在编译器中复用表达式求值逻辑

# 4. 组合并发送（同方法1）

方法3：批量生成章节内容

# 1. 检查图书写作进度
cat book/PROGRESS_REPORT.md

# 2. 根据WORKFLOW.md的步骤执行
# 创建分支 → 建立目录 → 生成提示词 → 发送代理 → 技术审查

# 3. 质量检查
cat book/IMPLEMENTATION_SUMMARY.md

📝 章节质量检查清单

内容完整性（必须全部满足）

[ ] 本章概述: 1–3句话，说明问题、位置、学习价值
[ ] 动机场景: 真实工程场景，说明缺失的痛点
[ ] 核心概念: 通俗解释，1–3个图示占位符（[图X：描述]）
[ ] EP对应关系: 明确目录、关键类、方法、设计模式
[ ] 实战流程: 可运行的步骤，预期输出，故障排查
[ ] AI上下文设计: 源码/文档/测试文件列表，组织说明
[ ] AI Prompt模板: 至少1个可直接复用的Prompt
[ ] AI应该/不该做: 各3–5条明确清单
[ ] 验证与回滚: 测试命令、检查点、git回滚方案（4种方案）
[ ] 练习题: 3–5道，含手工版和AI协作版，每题有提示
[ ] 本章小结: 总结收获，预告下一章，流水线位置图

AI协作线硬性要求

[ ] ✅ 至少1个可直接复制给AI的Prompt模板
[ ] ✅ 说明如何验证AI的输出（独立小节）
[ ] ✅ AI应该/不该做清单各包含3–5条
[ ] ✅ 提供4种Git回滚方案

🛠️ 常用命令

图书项目管理

# 查看整体规划
cat book/BOOK_IMPLEMENTATION_PLAN.md

# 查看工作流
cat book/WORKFLOW.md

# 查看进度报告  
cat book/PROGRESS_REPORT.md

# 查看实现总结
cat book/IMPLEMENTATION_SUMMARY.md

章节生成与验证

# 生成章节完整Prompt（系统级 + 章节级）
cat book/SYSTEM_PROMPT.md book/assets/prompts/chapterXX_prompt.md > full_prompt.md

# 验证代码示例可编译（针对具体EP）
cd ep{number}
mvn clean compile
mvn test

# 运行示例程序
mvn exec:java -Dexec.args="src/main/resources/example.cymbol"

质量控制

# 检查章节字数（目标：8000–12000字）
wc -w book/01_fundamentals/chapter01.md

# 检查代码示例数量（目标：3–5个）
grep -c "```java" book/01_fundamentals/chapter01.md

# 检查图示占位符（目标：3–5个）
grep -c "\[图" book/01_fundamentals/chapter01.md

# 检查AI Prompt模板（目标：至少1个）
grep -c "Prompt模板" book/01_fundamentals/chapter01.md

📊 进度跟踪模板

章节完成状态表

| 章节 | 状态 | 完成日期 | 字数 | 代码示例数 | AI Prompt数 | |------|------|---------|-------|------------|--------------| | 第0章 | ⏳ 待开始 | - | - | - | - | | 第1章 | ✅ 已完成 | 2026-01-12 | 8500 | 4 | 2 | | 第2章 | ⏳ 进行中 | - | 6500 | 3 | 1 |

进度里程碑

| 阶段 | 目标日期 | 状态 | 备注 | |------|---------|------|------| | 阶段1：基础设施 | 第2周 | ✅ 已完成 | 完成前言+第1章（样板） | | 阶段2：模块1 | 第7周 | ⏳ 进行中 | 完成第2–5章 | | 阶段3：模块2 | 第11周 | ⏳ 待开始 | 完成第6–9章 |

🔧 AI协作线模板

类型A：功能实现Prompt模板

请在不破坏现有语法的前提下，为Cymbol语言增加[新语法特性]。

任务目标：
- 实现从[旧语法]到[新语法]的平滑过渡
- 确保与现有编译器流水线兼容

具体要求：
1. 修改`ep{ep_number}/src/main/antlr4/Cymbol.g4`语法文件
2. 更新相关的AST节点类
3. 实现对应的Visitor方法
4. 添加测试用例验证功能

参考上下文文件：
- 源码：`ep{ep_number}/src/main/antlr4/Cymbol.g4`
- 测试：`ep{ep_number}/src/test/java/.../{相关测试}Test.java`

期望输出：
1. 修改后的`Cymbol.g4`文件（标注新增部分）
2. 新增或修改的AST节点类代码
3. Visitor方法的实现代码
4. 完整的测试类代码

类型B：优化实现Prompt模板

请根据以下优化规则，将这段三地址码转换为优化形式：

输入代码：
```java
{输入IR代码示例}

优化目标：

常量折叠：在编译时计算常量表达式
死代码消除：移除未使用的赋值语句
公共子表达式消除：识别重复计算并复用结果

期望输出：

优化后的IR代码（标注优化点）
优化过程的详细解释
验证命令和预期结果


### 类型C：测试生成Prompt模板

请为[功能模块]生成一组完整的测试用例，覆盖以下场景：

测试覆盖要求：

正常情况测试（至少2个）
边界情况测试（至少2个）
错误情况测试（至少1个）

具体要求：

使用JUnit 5和AssertJ
提供@DisplayName注解的中英文双语描述
包含参数化测试用例（@ParameterizedTest）

期望输出：

完整的测试类代码
每个测试用例的详细说明
运行测试的Maven命令


## ⚠️ 常见问题与解决方案

### 问题1：章节提示词不完整
**症状**: 生成的章节缺少AI协作线或练习题
**原因**: 章节提示词未完整填充所有占位符
**解决**: 
1. 检查`book/assets/prompts/chapterXX_prompt.md`是否完整
2. 对照`CHAPTER_TEMPLATE.md`的检查清单逐一核对
3. 补充缺失部分后重新生成

### 问题2：代码示例编译失败
**症状**: 章节中的代码示例无法通过`mvn compile`
**原因**: 代码示例与仓库实际代码不一致
**解决**:
1. 进入对应EP目录验证代码
2. 更新章节中的代码示例
3. 确保示例路径正确

### 问题3：AI协作线过于简略
**症状**: AI应该/不该做清单不足3条，缺少验证策略
**原因**: 未遵循硬性要求
**解决**:
1. 参考`SYSTEM_PROMPT.md`第4.4节
2. 确保包含4种Git回滚方案
3. 添加具体的测试验证命令

### 问题4：章节连贯性差
**症状**: 读者不理解本章与前后章的关系
**原因**: 缺少"你现在站在哪"的流水线位置说明
**解决**:
1. 在章节小结添加编译器流水线位置图
2. 明确说明本章输出如何被下一章使用
3. 添加跨章引用（如"第X章详细讲解了..."）

## 📈 最佳实践

### 写作风格最佳实践
1. **使用第二人称"你"** - 营造学习陪伴感
2. **避免学术化表达** - 保持工程实践语调
3. **复杂概念多角度解释** - 比喻 + 代码 + 图表
4. **适时提醒暂停思考** - "动手实验前先理解概念"

### 代码示例最佳实践  
1. **只给关键片段** - 完整代码以仓库为准
2. **代码附带中文注释** - 解释设计意图
3. **强调常见陷阱** - 标注容易出错的地方
4. **提供可运行示例** - 给出具体命令和预期输出

### AI协作线最佳实践
1. **上下文精确设计** - 明确列出需要提供的文件
2. **Prompt模板可复用** - 设计通用模板，填充具体参数
3. **验证策略具体化** - 提供具体的测试命令和检查点
4. **回滚方案简单化** - 提供一键式Git回滚命令

---

*版本: v1.0 | 垂直职责: 技术图书写作 | 2026-01-12*

Agent Skills: 技术图书写作专家 (Tech Blogger Agent)

Install this agent skill to your local

Skill Files