用途：为 Astro 仓库的 TypeScript/JavaScript 源码撰写面向贡献者的注释。目标读者是数月或数年后、没有任何当前上下文的贡献者，只能看到 HEAD 版本代码。不适用于终端用户文档：packages/astro/src/types/public/config.ts 与 packages/astro/src/core/errors/errors-data.ts 中带 @docs 的 JSDoc 由外部工具抓取并发布到 Astro 文档站，需遵循 packages/astro/src/core/errors/README.md 并请文档团队评审；types/public/** 中其他 JSDoc 面向编辑器 IntelliSense，应写给 Astro 用户。
三类注释：文件/模块概述（文件顶部 /** /）作解释，说明模块存在原因、概念术语、各部分关系与设计理由；条目文档（声明上方 /* */）作参考，写明行为、参数、返回值、抛错、不变量；行内注释（体内 //）只写代码无法表达的理由，如约束、带链接的临时方案、非显然耦合。三者不可混用。
写法要求：先平实说明返回值或作用，用短句，避免不必要的内部术语，说明调用方可见的意外行为（回退、限制、歧义、副作用、返回 undefined/null/空结果的条件），预期调用方能区分或恢复时记录抛错，不描述实现细节。签名无法体现关系时加示例，如重载选择、可选/剩余参数、公开入口、歧义路由回退、结果含义不直观；示例前用文字说明目的与预期，片段尽量精简。模块文档应写持久概念或架构边界，不要罗列导出。
删除测试：写注释前先问读者能否从代码本身获得该信息；名字、类型、结构已表达则不写，名字表达不了就改名字。需要注释的是不变量、理由、跨处耦合、带链接的临时方案、依赖的意外行为、模块定义的术语。
禁用写法：不逐行复述下一行代码；不叙述变更历史（@deprecated 例外）；不向评审者辩解；不重复声明名；不用模糊措辞；不用 emoji；不加临时分节横幅。
仓库约定：@param name - description、@returns、@throws 陈述契约，仅在签名有歧义时用花括号包类型，@example 用 ```js 代码块；交叉引用用 {@link} / {@linkcode}；@internal 仅表意图，不能替代访问修饰符；@deprecated 要写迁移方式与移除时间；TODO 用 // TODO:，破坏性变更窗口用 // TODO: remove in Astro <N>，本仓库没有 FIXME。临时方案、HACK、回归防护、依赖意外行为必须链接对应 issue 或 PR。
编辑既有代码：保留原有注释，行为变更时扩写或修正具体语句；注释失真须在同一 diff 修正；注释密度与周围一致。完成前单独重读 diff 中注释，检查是否通过删除测试、是否提及对话或评审者、临时方案是否带链接、无 diff 上下文者能否读懂，未通过者修正或删除。