Back to Details

tutorial-writing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementation Tutorial Generator

实现教程生成器

Generate exhaustive, educational implementation guides that go far beyond typical planning output. The goal is to enable a "tutorial doc + build-it-yourself" workflow where the developer stays connected to the work and learns by implementing.
生成详尽、兼具教育意义的实现指南，远超常规规划输出的深度。目标是打造“教程文档+亲手构建”的工作流，让开发者全程参与工作并通过实现过程学习。

Philosophy

设计理念

This skill exists because reviewing large AI-generated PRs often feels like "ugh"—you're disconnected from the work, rubber-stamping changes you don't fully understand. The alternative:
  1. AI researches deeply and produces a comprehensive tutorial document
  2. Human implements following the guide, staying connected to decisions
  3. Result: Faster than pure manual work, but you understand what you built
The output is a markdown document, NOT code changes. You are teaching, not doing.
该技能的存在是因为审阅AI生成的大型PR通常让人感觉“唉”——你和实际工作脱节，只是在盖章通过那些你并不完全理解的改动。替代方案：
  1. AI深入调研并生成全面的教程文档
  2. 人类动手实现，遵循指南并全程参与决策
  3. 结果：比纯手动工作更快，但你完全理解自己构建的内容
输出是markdown文档，而非代码改动。你的角色是教学，而非代劳。

Workflow

工作流

Step 1: Gather Requirements

步骤1：收集需求

Before doing any research, ask the user:
  • What feature or change do you want to implement?
  • Where should I save the tutorial document? (Suggest a path like 
    private/tutorials/
    or the project's docs folder)
在开展任何调研前，询问用户：
  • 你想要实现什么功能或改动？
  • 我应该将教程文档保存到哪里？（建议路径如
    private/tutorials/
    或项目的docs文件夹）

Step 2: Deep Codebase Research

步骤2：深度代码库调研

Spend significant time exploring the codebase. This is NOT optional—the tutorial must be grounded in the actual code, not abstract principles. Research:
  • Architecture: How is the project structured? What are the key directories and their purposes?
  • Patterns: What conventions does this codebase follow? How are similar features implemented?
  • Related Code: Find 2-3 existing implementations most similar to what we're building. Study them in depth.
  • Dependencies: What libraries/frameworks are used? What APIs are available?
  • Testing: How does this project test features? What testing utilities exist?
  • Types: What TypeScript types or schemas are relevant?
Reference specific files and line numbers. The tutorial should feel like it was written by someone who knows this codebase intimately.
投入充足时间探索代码库。这一步必不可少——教程必须基于实际代码，而非抽象原则。调研内容包括：
  • 架构：项目的结构如何？核心目录及其用途是什么？
  • 模式：代码库遵循哪些约定？类似功能是如何实现的？
  • 相关代码：找到2-3个与我们要构建的内容最相似的现有实现，深入研究它们。
  • 依赖项：使用了哪些库/框架？有哪些可用的API？
  • 测试：项目如何测试功能？存在哪些测试工具？
  • 类型定义：哪些TypeScript类型或 schema 与之相关？
引用具体文件和行号。教程要给人一种由对代码库了如指掌的人撰写的感觉。

Step 3: Generate the Tutorial Document

步骤3：生成教程文档

Write a comprehensive markdown document following this structure:
按照以下结构撰写全面的markdown文档：

Tutorial Document Structure

教程文档结构

markdown
undefined
markdown
undefined

[Feature Name] Implementation Guide

[功能名称] 实现指南

A step-by-step tutorial for implementing [feature] in [project name]. Estimated implementation time: [X milestones, ~Y hours of focused work]
一份在[项目名称]中实现[功能]的分步教程。 预计实现时间：[X个里程碑，约Y小时专注工作]

Overview

概述

[2-3 paragraphs explaining what we're building and why. Include the user-facing value and technical motivation. This should excite the reader about what they'll learn.]
[用2-3段文字说明我们要构建的内容及其原因，涵盖用户价值和技术动机，让读者对即将学习的内容充满兴趣。]

Background & Context

背景与上下文

[Deep dive into the surrounding systems. Teach the reader about:
  • How the relevant parts of the codebase work today
  • Historical context if relevant (why things are the way they are)
  • Key abstractions they need to understand
  • Reference specific files: "The current implementation lives in 
    src/features/auth/
    (see especially 
    auth-provider.tsx:45-120
    )"]
[深入剖析相关系统，向读者讲解：
  • 代码库相关部分当前的工作方式
  • 相关历史背景（若有）——事物为何是当前状态
  • 读者需要理解的核心抽象概念
  • 引用具体文件：“当前实现位于
    src/features/auth/
    （尤其参见
    auth-provider.tsx:45-120
    ）”]

Technical Landscape

技术全景

[Map out the territory:
  • Relevant existing components/modules
  • Data flow and state management patterns used here
  • API contracts and type definitions
  • External dependencies involved
  • Constraints and gotchas to be aware of]
[梳理技术版图：
  • 相关的现有组件/模块
  • 此处使用的数据流和状态管理模式
  • API契约和类型定义
  • 涉及的外部依赖项
  • 需要注意的约束和陷阱]

Design Rationale

设计依据

[Explain the approach we're taking and WHY:
  • What alternatives were considered?
  • Why is this approach better for THIS codebase?
  • What tradeoffs are we making?
  • How does this align with project conventions?]
[说明我们采用的方法及其原因：
  • 考虑过哪些替代方案？
  • 为何该方法对本代码库更适用？
  • 我们做出了哪些权衡？
  • 这如何与项目约定保持一致？]

Implementation Milestones

实现里程碑

[The core of the tutorial. Each milestone should be:
  • Small enough to complete in one sitting
  • Verifiable—you can SEE it works before moving on
  • Buildable—each milestone builds on the previous]
[教程的核心部分。每个里程碑需满足：
  • 足够小，可在单次工作中完成
  • 可验证——你能看到它正常工作后再进入下一步
  • 可递进——每个里程碑基于前一个构建]

Milestone 1: [Foundation/Setup]

里程碑1：[基础/准备工作]

Objective: [What we're accomplishing]
Why this first: [Rationale for ordering]
Files to create/modify:
  • path/to/file.ts
    - [what changes and why]
  • path/to/other.ts
    - [what changes and why]
Implementation approach: [Detailed explanation of WHAT to build, not copy-paste code. Describe:
  • The structure and key functions needed
  • How it connects to existing code
  • Patterns to follow from similar implementations
  • Edge cases to handle]
Verification:
  • [Specific test to run or behavior to observe]
  • [Another verification step]
Checkpoint: After this milestone, you should be able to [specific observable behavior].
目标：[我们要完成的内容]
为何优先进行此步骤：[排序依据]
需创建/修改的文件：
  • path/to/file.ts
    - [改动内容及原因]
  • path/to/other.ts
    - [改动内容及原因]
实现方法： [详细说明要构建的内容，而非提供复制粘贴的代码。描述：
  • 所需的结构和核心函数
  • 如何与现有代码关联
  • 需遵循的类似实现模式
  • 要处理的边缘情况]
验证方式：
  • [具体要运行的测试或要观察的行为]
  • [另一项验证步骤]
检查点：完成此里程碑后，你应该能够[具体可观察的行为]。

Milestone 2: [Core Functionality]

里程碑2：[核心功能]

[Same structure as above...]
[与上述结构相同……]

Milestone 3: [Integration]

里程碑3：[集成]

[Same structure...]
[与上述结构相同……]

Milestone N: [Polish & Edge Cases]

里程碑N：[优化与边缘情况]

[Final milestone often handles:
  • Error states and edge cases
  • Loading states and UX polish
  • Documentation and types cleanup]
[最终里程碑通常处理：
  • 错误状态和边缘情况
  • 加载状态和UX优化
  • 文档和类型定义清理]

Testing Strategy

测试策略

[How to thoroughly test this feature:
  • Unit test approach and key test cases
  • Integration test considerations
  • Manual testing checklist
  • Edge cases that MUST be tested]
[如何全面测试该功能：
  • 单元测试方法和核心测试用例
  • 集成测试注意事项
  • 手动测试清单
  • 必须测试的边缘情况]

Risks & Mitigations

风险与缓解措施

[What could go wrong?
  • Technical risks (performance, compatibility, etc.)
  • UX risks (confusing behavior, accessibility issues)
  • Maintenance risks (technical debt, future conflicts)
  • How to mitigate or monitor each]
[可能出现哪些问题？
  • 技术风险（性能、兼容性等）
  • UX风险（行为混淆、可访问性问题）
  • 维护风险（技术债务、未来冲突）
  • 如何缓解或监控每项风险]

Going Further

拓展方向

[Optional extensions beyond the core implementation:
  • Nice-to-have improvements
  • Future enhancements to consider
  • Related features this enables]
[核心实现之外的可选扩展：
  • 锦上添花的改进
  • 可考虑的未来增强功能
  • 此功能赋能的相关特性]

References

参考资料

[Specific pointers for the implementer:
  • Key files: 
    path/to/file.ts:123
    - description
  • Related PRs or issues if known
  • External documentation links
  • Similar implementations in the codebase to reference]

---
[为实现者提供的具体指引：
  • 核心文件：
    path/to/file.ts:123
    - 描述
  • 已知的相关PR或议题
  • 外部文档链接
  • 代码库中可参考的类似实现]

---

Quality Standards

质量标准

The tutorial must:
  1. Be exhaustive: Go deeper than typical plan mode output. If it takes 30+ minutes to generate, that's fine—the user is trading AI time for their own learning.
  2. Teach, don't just instruct: Explain WHY at every step. The reader should understand the system better after reading, not just know what to type.
  3. Reference real code: Every claim about "how the codebase works" should point to specific files and line numbers. No hand-waving.
  4. Enable independence: After reading the tutorial, the developer should be able to implement WITHOUT coming back to ask more questions.
  5. Verify at each step: Every milestone must have concrete verification. No "now the feature should work"—specify HOW to verify.
  6. Go beyond the obvious: The tutorial can extend beyond where a typical PR would stop. Suggest polish, tests, documentation—even if the user might skip some of it.
教程必须满足：
  1. 详尽全面：比常规规划模式的输出更深入。如果生成需要30分钟以上，也完全没问题——用户愿意用AI的时间换取自身的学习机会。
  2. 重在教学，而非指令：在每一步都说明原因。读者读完后应更理解系统，而非只知道要输入什么。
  3. 引用真实代码：每一个关于“代码库工作方式”的表述都应指向具体文件和行号。不能含糊其辞。
  4. 支持独立完成：读完教程后，开发者应能独立实现，无需回头再提问。
  5. 分步验证：每个里程碑都必须有具体的验证方式。不能只说“现在功能应该正常工作”——要明确说明如何验证。
  6. 超越常规边界：教程可以延伸至常规PR不会涉及的范围。建议优化、测试、文档相关的内容——即便用户可能会跳过其中部分。

Output Behavior

输出行为

  1. Ask for output path before starting (suggest reasonable default)
  2. Write the complete tutorial to the specified path
  3. Summarize what was created and suggest how to proceed
  1. 开始前询问输出路径（建议合理的默认路径）
  2. 将完整教程写入指定路径
  3. 总结已创建的内容并建议后续步骤

Example Invocations

调用示例

/tutorial Add dark mode support to the component library

/tutorial Implement real-time notifications using WebSockets

/tutorial Refactor the data fetching layer to use React Query

/tutorial Add comprehensive error boundaries throughout the app
/tutorial 为组件库添加深色模式支持

/tutorial 使用WebSockets实现实时通知

/tutorial 重构数据获取层以使用React Query

/tutorial 在整个应用中添加全面的错误边界

Remember

谨记

You are not generating code. You are generating a TEACHING DOCUMENT. The human will write the code themselves, using your guide. This keeps them connected to the work, helps them learn the codebase, and produces better outcomes than reviewing AI-generated PRs.
Take your time. Be thorough. The user explicitly wants depth over speed.
你不是在生成代码，而是在生成教学文档。人类会自行编写代码，以你的指南为参考。这能让他们全程参与工作，帮助他们了解代码库，并且比审阅AI生成的PR产生更好的结果。
慢慢来，要详尽。用户明确想要深度而非速度。