指导与技术文档
通过结对编程和适时反馈帮助初级队友成长，为架构决策编写 ADR，并维护值得他人信赖的持续更新文档。
指导与技术文档 是 CoddyKit 上的免费 Frontend Academy 课时。 这是第 3 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Frontend Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Frontend Academy 课程共包含 4 节课。
高级工程师意味着成就他人
在高级工程师阶段，您的职责不是编写最多的代码，而是让团队变得更好。指导初级开发者，编写能够传播您的知识的文档，进行有教学价值的代码审查，并设计架构，让其他人能够快速而安全地推进工作。
通过结对编程进行指导
结对编程是帮助初级开发者快速成长的方式。请坐在一起（或共享屏幕），让对方操作，而您负责引导。请克制住接管操作的冲动——解释您的思考过程，并提出苏格拉底式的问题。
难度合适的挑战
请给初级开发者安排略高于其当前能力的任务。太容易就无法成长；太难则会让人不堪重负并感到沮丧。请做好判断：“我认为您在获得一点帮助后可以完成这项任务——如果遇到困难，我很乐意和您结对。”
将代码审查作为教学
对于初级开发者提交的 PR，请解释每条非简单评论背后的原因。关联相关文档、之前的 PR 或文章。糟糕的审查：“使用 useCallback”。良好的审查：“这个函数在每次渲染时都会重新创建——将它传给经过记忆化处理的子组件会导致不必要的重复渲染。useCallback 可以将它记忆化。这里有一个我们采用这种做法的示例 PR：#1234”。
架构决策记录（ADR）
ADR 用于记录重要的架构选择：我们决定了什么、为什么这样决定、考虑过哪些替代方案，以及接受了哪些权衡。未来的您会感谢现在的您。
# ADR-0007: Use TanStack Query for server state
Date: 2026-05-01
Status: Accepted
## Context
We currently scatter useEffect+fetch+useState patterns across the app.
Cache invalidation is inconsistent, race conditions cause stale data.
## Decision
Adopt TanStack Query (@tanstack/react-query v5) for all server state.
## Consequences
+ Built-in caching, deduplication, optimistic updates.
+ Standard pattern across team.
- Adds ~13KB gzipped.
- Team needs to learn query keys conventions.
## Alternatives Considered
- SWR: smaller, but fewer features (no mutations).
- Apollo Client: overkill (we don't use GraphQL).
- Custom hook: doesn't solve cache invalidation.
## References
- React Query docs: ...ADR 存放在哪里
请将 ADR 按顺序编号，并存放在代码仓库中的 docs/adr/。它们与所描述的代码放在一起。工具包括 adr-tools 和 log4brains，后者提供可浏览的网页界面。
README 质量
每个包、库和主要功能都需要 README。请包含：它的用途、安装方法、使用方法（附代码示例）、贡献方式、运行测试的方法以及调试方法。README 驱动开发意味着先编写 README，再按照这份规范进行构建。
行内代码注释——何时使用
注释应该解释为什么，而不是是什么。代码会展示是什么。注释应解释：业务规则、不明显的权衡、工单或错误的链接，以及容易踩坑之处的警告。
// BAD: comment restates the code
// Increment counter by 1
counter++;
// GOOD: comment explains business context
// Stripe webhook can arrive twice — increment only if signature is fresh.
// See: https://stripe.com/docs/webhooks/best-practices#idempotency
if (!seen.has(event.id)) counter++;运维任务操作手册
请记录如何执行重复性或高风险的运维任务，例如：“如何轮换 Stripe 接口密钥”“如何从部署失败中恢复”“如何调试缓慢的接口响应”。新团队成员可以按照文档操作，而不必呼叫您。
持续更新的文档
过时的文档比没有文档更糟糕。请为文档标注日期，每季度审查一次。删除无人更新的文档。更好的做法是从代码生成文档（组件使用 Storybook，接口使用 TypeDoc，端点使用 OpenAPI）。
技术分享与交流会
请为团队进行 20–30 分钟的分享，介绍您学到的内容：新库、调试经历，或您发现有用的模式。这会迫使您整理思路，也能教会其他人。
建立心理安全感
害怕提问的初级开发者无法成长。请让“我不知道”变得很正常。营造允许犯错的环境——庆祝复盘，而不是追究责任。作为高级工程师，您的反应会为团队定下基调。
英雄式编码的陷阱
不要成为独自修复每次生产环境事故的人。请记录修复方法，下次与队友结对完成，并自动化诊断过程。一个需要依赖您的英雄式救火才能运转的团队是脆弱的。
快速检查
架构决策记录（ADR）的主要用途是什么？
回顾：指导与文档
高级工程师意味着成就他人，而不是编写最多的代码。进行结对编程；通过代码审查教学；安排难度合适的挑战。将决策原因记录在 docs/adr/ 中的 ADR 里。为每个包编写 README。注释解释为什么，而不是什么。为运维任务编写操作手册。持续更新的文档（Storybook、TypeDoc、OpenAPI）胜过静态 Markdown。建立心理安全感。避免英雄式编码。
常见问题解答
「指导与技术文档」课时是免费的吗？
是的 — 「指导与技术文档」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Frontend Academy 课程的其余内容，请升级到 CoddyKit PRO。 Frontend Academy 课程共包含 4 节课。
「指导与技术文档」这节课中我会学到什么？
通过结对编程和适时反馈帮助初级队友成长，为架构决策编写 ADR，并维护值得他人信赖的持续更新文档。 你通过在浏览器中直接运行的动手代码来练习 Frontend Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 Frontend Academy 需要有经验吗？
无需任何先前经验。CoddyKit 上的 Frontend Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 3 节课，共 4 节。
「指导与技术文档」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 Frontend Academy 课中编写并运行代码吗？
能。每节 Frontend Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。