尧图网站建设 
Astro 源码注释规范面向贡献者的 JSDoc 契约、行内注释与删除测试【免费下载链接】astroThe web framework for content-driven websites. ⭐️ Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/as/astroAstro 仓库维护了一套严格的源码注释规范它不是给最终用户看的 API 文档而是写给数月乃至数年后、拿着仓库 HEAD 版本、却完全没有你当前上下文的贡献者读的。读完本篇你将掌握 Astro 贡献者注释的三层分工模块概述 / 条目文档 / 行内注释、删除测试判据、变通方案workaround必须附 issue 链接的硬性要求、七类被明令禁止的注释反模式以及deprecated、TODO: remove in Astro N等仓库专属惯例并在需要向 Astro 提交 PR 时写出符合社区评审标准的注释。适用边界贡献者注释 vs 用户文档这条规范首先划清了一条容易踩线的边界它只管贡献者面向的.ts/.js源码注释不适用于面向最终用户的文档。仓库中有三类注释不在此管辖范围内编辑它们需要走完全不同的流程docs标签的 JSDoc 块——位于 packages/astro/src/types/public/config.ts 和 packages/astro/src/core/errors/errors-data.ts 中会被外部docgen工具抓取并发布到 Astro 官方文档站。编写这类内容需遵循 packages/astro/src/core/errors/README.md 中的错误信息写作指南并且必须经过文档团队docs team评审——CI 会在types/public/**变动时重新生成参考文档。types/public/**下的其他 JSDoc——它们通过编辑器的 IntelliSense 直接暴露给用户。要站在Astro 用户正在建站的视角写作而不是贡献者正在读源码的视角。除此之外规范正文讨论的所有内容都针对贡献者在 HEAD 上读取的源码。仓库中的真实docs样例config.ts中每个配置项都带有结构化 JSDoc 块包含name、type、default、version、description等标签例如 config.ts 中的/** * name server.port * type {number} * default 4321 * description * Set which port the dev server should listen on. * * If the given port is already in use, Astro will automatically try the next available port. */ port?: number;这些块的用户是配置astro.config.mjs的建站者描述的是配置契约本身绝不允许夹带内部实现说明比如某个内部归一化函数的行为细节——这正是该技能文档边界章节反复强调的反面案例。errors-data.ts的头部注释本身就是一条边界声明见 errors-data.ts// BEFORE ADDING AN ERROR: Please look at the README.md in this folder for general guidelines on writing error messages // Additionally, this code, much like types/public/config.ts, is used to generate documentation, so make sure to pass // your changes by our wonderful docs team before merging!文件内每条错误都按 README.md 的规范用docs、message、see、description标签组织例如UnknownCompilerErrorerrors-data.ts就是一个完整样例description从用户视角解释发生了什么、为什么、该怎么做而不是描述抛错逻辑的内部实现。读者的定义一个只有 HEAD 的陌生人规范把目标读者定义得非常具体一位精通 TypeScript、但完全没有你当前上下文的 Astro 贡献者——他看不到你这轮对话、看不到你的 PR、看不到关联 issue、也看不到你的 diff他只能看到仓库 HEAD 这一份代码。由这个前提直接推出两条铁律永远不要叙述变更历史。now现在、previously以前、no longer不再、the new approach新方案这类词在 HEAD 上毫无意义——那里只存在一种做法。注释要陈述代码如何工作而不是它如何演变而来。唯一的例外是deprecated声明见后文本仓库的惯例因为它描述的是契约的未来而读者确实需要知道。永远不要对评审者说话。注释不是用来论证我的改动是正确的——this properly handles X这正确处理了 X这类辩解属于 PR 描述不属于源码。注释必须为代码现状提供永久性辩护而不是为你的改动辩护。三类注释三件不同的事类型语法职责内容文件 / 模块概述文件顶部的/** */解释Explanation模块为什么存在、它定义的概念和术语、各部分如何关联、设计动因条目文档Item docs直接位于声明上方的/** */参考Reference契约行为、参数、返回值、抛出的错误、不变量。中性、事实性行内注释函数体内的//动机Rationale只有代码自己说不出来的东西约束、带 issue 链接的变通方案、不明显的耦合这三类职责严格分离对应 Diátaxis 文档框架中解释 / 参考 / 动机的三分法技能文档在 References 一节明确以此为理论来源。两个典型的混淆方向被点名禁止实现细节不属于/** */契约——应下沉为函数体内的//注释契约不应散落在行内注释里——应挂在声明上方的文档块上。行为文档为人类读者写契约而非翻译实现当一条声明确实需要条目文档时写作目标是给人类读者描述契约而不是把实现逐行翻译成文字。规范同时强调这并不意味着每个函数都要写 JSDoc——名称、类型和结构本身应当能承载直观行为承载不了就先改名字。具体写作要求先用一句通俗语言说明函数返回什么、完成了什么使用短句或中句每句只承载一个主要思想调用方不需要时避免内部术语Astro 黑话。确需使用技术术语就在同一段里解释描述调用方可见的、可能令人意外的注意点回退行为、工作量的上限、含糊的结果、重载的匹配顺序、副作用以及返回undefined、null、空结果或其他不确定值的条件当调用方需要区分或恢复时文档化抛出的错误除非调用方理解行为或安全使用 API 必须否则不描述实现细节。何时必须加示例当行为依赖于签名无法清晰表达的关系时应添加example。Astro 与 TypeScript 中最常见的五类场景哪个重载会被选中参数如何映射到可选参数或 rest 参数哪个公开的 Astro 入口点暴露了实现在别处的符号re-export 场景含糊路由、不完整配置或缺失内容时的回退行为含义无法从类型直接看出的返回值。示例的写法也有规范先用散文引出代码块说明它演示什么、预期结果是什么代码片段保持最小、自包含并且站在 Astro 用户或拥有该契约的内部调用方的视角书写。模块文档描述持久的概念模块级/** */应当描述一个持久的概念、架构边界或设计理由。禁止罗列文件中的各个导出项来总结文件——随着符号被增删改名这类清单很快就会过时stale。如果一个模块没有值得解释的持久概念那就写一行简短描述或者干脆不写概述。删除测试The Deletion Test写任何注释之前先问自己这条注释陈述的信息读者能否从代码本身恢复出来如果信息已经被名称、类型或结构承载就不要写注释如果名字承载不了去改进名字。真正有资格获得注释的信息一个不变量、一个动机、与别处代码的耦合、带链接的变通方案、某个依赖令人意外的行为、以及该模块定义的专业术语。编辑旧代码时同一测试反向适用不再通过的注释应当删除而不是留着慢慢腐烂。技能文档把这句收在自检清单的末尾并给出总基调删除是默认选项缺失的注释比误导性的注释更便宜。变通方案必须链接 issue 或 PR这是本仓库一条高度一致、可被机器核验的硬性规则**任何解释变通方案workaround、HACK、回归防护regression guard或依赖意外行为的注释必须链接到动机所在的 GitHub issue 或 PR。**链接的存在让未来的读者能判断这个变通方案是否仍然必要——技能文档的原话是没有链接的变通方案与一个错误无法区分。规范给出的标准示例// Handle recommended nanostores. Only nanostores/preact is required from our testing! // Full explanation and related bug report: https://github.com/withastro/astro/pull/3667 nanostores/preact,这条规则在仓库中并非纸上谈兵。packages/astro/src/vite-plugin-environment/index.ts 里的ALWAYS_NOEXTERNAL列表就是规范风格的活体样本每个条目都是一行理由 issue/PR 编号const ALWAYS_NOEXTERNAL [ // This is only because Vites native ESM doesnt resolve exports correctly. astro, // Vite fails on nested .astro imports without bundling astro/components, // Handle recommended nanostores. Only nanostores/preact is required from our testing! // Full explanation and related bug report: https://github.com/withastro/astro/pull/3667 nanostores/preact, // Must be bundled so the prerender output resolves Astros own copy, not an // older hoisted version from another dependency. See https://github.com/withastro/astro/issues/17508 neotraverse, ];注意其中的措辞都是现在时动机Vite fails on...、Must be bundled so...而不是我们改了它因为……式的历史叙述——恰好同时满足读者铁律和变通链接两条规则。七类被禁止的注释模式技能文档逐一点名并给出了改写对照这是全篇最具操作性的部分1. 复述下一行代码。看到就删// Increment the generation counter generation 1;2. 叙述变更历史。改写为现在时的动机说明// BAD: We now resolve lightningcss from the users root instead of ours. // GOOD: lightningcss is an optional peer dep, so it resolves from the users project root.3. 对评审者的辩解。论据移回 PR 描述// BAD: This correctly handles the multi-encoded path from the bug report. // GOOD: A path still encoded after MAX_DECODE_ITERATIONS is rejected, so // middleware and routing can never disagree on the decoded path.4. 换了个说法的 JSDoc。复述声明名的文档块等于没说// BAD: /** Compiles the styles. */ function compileStyles(...) // GOOD: /** Rewrites relative url() references in css against base, leaving * absolute and data URLs untouched. */ function compileSkills(...)注意示例中 GOOD 版本说明了行为契约——重写相对url()、不动绝对与 data URL——而不是翻译函数名。5. 含糊的套话。some cases、various reasons、handles edge cases、etc.——要么点名具体是什么要么删掉整句。6. Emoji。源码中全面禁用注释也不例外这是仓库级政策。7. 临时分区横幅如// ----- helpers -----、// TYPES 。本仓库没有// #region折叠惯例不要添加横幅。如果一个文件长到你伸手去找横幅那是该拆分文件的信号不是该装饰它的信号。本仓库的注释惯例以下惯例是 Astro 源码特有的约定脱离仓库语境可能不成立JSDoc 标签。param name - description、returns、throws用于陈述契约只有当签名本身有歧义时才用花括号包裹类型如returns {Promisestring}非显而易见的用法配example加js围栏代码块。交叉引用。使用{link Symbol}/{linkcode Symbol}而不是裸写符号名这样符号改名时引用会自动更新编辑器也能跳转到目标。internal。标记不属于公开 API 面的符号。它只是约定——这个仓库没有 typedoc 或 api-extractor 来剥离它——所以它表达的是意图不能替代真正的访问控制手段。deprecated。先说迁移方案再说移除时间点仓库示例/** deprecated Use the instance method cookies.consume() instead. This will be removed in Astro 7 */关键是说替代方案是什么而不只是此符号已废弃。这条面向未来的陈述属于读者需要的契约信息不属于被禁止的历史叙述——这正是读者铁律第 1 条预留的例外通道。TODO。延后工作用// TODO:有 issue 跟踪就附链接受破坏性变更窗口约束的工作使用既定句式// TODO: remove in Astro N。本仓库不存在FIXME——不要引入它。这句约定在源码中有直接证据例如 packages/astro/src/content/runtime.ts 中的两处// TODO: remove in Astro 8 warnForPropertyAccess( logger, result.data, slug, [content] Attempted to access deprecated property on ${collection} entry.\nThe slug property is no longer automatically added to entries. Please use the id property instead., );这里的措辞细节值得品味TODO 本体只说在 Astro 8 移除而给用户看的警告字符串才解释替代路径——两条信息各归其位互不污染。编辑已有代码时的三条纪律保留既有注释。如果你的改动改变了行为就扩展或修正对应的那段散文——绝不替换成通用套话。删除来之不易的上下文比留一条略微过时的注释更糟。注释被你的改动说假了就在同一个 diff 里修好。过时的注释比没有注释更坏。匹配周边的注释密度。文档密集的模块新增条目应达到同等水准也不要给本来就稀疏的模块泼一身注释。收尾自检只重读 diff 里的注释技能文档要求完成任何触碰注释的任务后把 diff 中新增的注释单独摘出来、脱离代码改动重读一遍逐条过四问每一条是否通过删除测试是否有引用对话、引用本次改动本身、或对评审者说话的每个变通方案是否链接了它的 issue 或 PR一个看不到 diff 的读者能否独立理解每一条不达标的修掉或删掉。删除是默认选项。自动化评估规则如何被验证这些规范并非仅靠人工评审执行。仓库中 .agents/skills/writing-comments/evals/evals.json 为写作注释技能定义了三个可断言的评估场景恰好覆盖规范的核心分支变通场景给定一段无上下文的resolveLightningcss源码要求补注释。断言包括注释必须位于函数体内//而非声明 JSDoc、必须说明lightningcss 是可选 peer dependency、须从用户项目根解析、必须包含追踪 issue 的准确 URL、禁止出现叙述 import/return 的行、禁止now/previously/correctly handles等历史或辩解措辞、禁止 emoji 与横幅。契约场景给定resolveEntry(collection, slug)精确匹配 → 回退 →undefined的语义无法从签名看出要求补写完整条目 JSDoc。断言包括开头散文描述调用方可见的结果而非复述函数名、JSDoc 覆盖精确匹配/回退/返回undefined三种条件、包含param collection -、param slug -、returns、带js围栏代码块的example、且不得宣称函数会抛错、不得谈论Map.get等实现细节。边界场景要求把一段normalizeAssets()的内部实现动机写进types/public/config.ts的docs块——正确行为是拒绝修改识别出docs块属于生成的用户文档、不在贡献者注释规则管辖内且需要遵循 errors/README.md 一类的仓库指引并取得 docs 团队评审。这三个场景与本技能规范文档.agents/skills/writing-comments/SKILL.md构成规范—验证闭环凡你在 Astro 中写下的注释都可以用同样的断言清单自测。参考规范本体.agents/skills/writing-comments/SKILL.md评估用例evals.json用户文档边界packages/astro/src/core/errors/README.md、packages/astro/src/types/public/config.ts、packages/astro/src/core/errors/errors-data.ts规范风格实证packages/astro/src/vite-plugin-environment/index.ts、packages/astro/src/content/runtime.ts理论来源技能文档 References 一节引用Diátaxis 框架解释 / 参考 / 动机三分法、TSDoc 标签规范【免费下载链接】astroThe web framework for content-driven websites. ⭐️ Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/as/astro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Astro 源码注释规范：面向贡献者的 JSDoc 契约、行内注释与“删除测试“
Astro 源码注释规范面向贡献者的 JSDoc 契约、行内注释与删除测试【免费下载链接】astroThe web framework for content-driven websites. ⭐️ Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/as/astroAstro 仓库维护了一套严格的源码注释规范它不是给最终用户看的 API 文档而是写给数月乃至数年后、拿着仓库 HEAD 版本、却完全没有你当前上下文的贡献者读的。读完本篇你将掌握 Astro 贡献者注释的三层分工模块概述 / 条目文档 / 行内注释、删除测试判据、变通方案workaround必须附 issue 链接的硬性要求、七类被明令禁止的注释反模式以及deprecated、TODO: remove in Astro N等仓库专属惯例并在需要向 Astro 提交 PR 时写出符合社区评审标准的注释。适用边界贡献者注释 vs 用户文档这条规范首先划清了一条容易踩线的边界它只管贡献者面向的.ts/.js源码注释不适用于面向最终用户的文档。仓库中有三类注释不在此管辖范围内编辑它们需要走完全不同的流程docs标签的 JSDoc 块——位于 packages/astro/src/types/public/config.ts 和 packages/astro/src/core/errors/errors-data.ts 中会被外部docgen工具抓取并发布到 Astro 官方文档站。编写这类内容需遵循 packages/astro/src/core/errors/README.md 中的错误信息写作指南并且必须经过文档团队docs team评审——CI 会在types/public/**变动时重新生成参考文档。types/public/**下的其他 JSDoc——它们通过编辑器的 IntelliSense 直接暴露给用户。要站在Astro 用户正在建站的视角写作而不是贡献者正在读源码的视角。除此之外规范正文讨论的所有内容都针对贡献者在 HEAD 上读取的源码。仓库中的真实docs样例config.ts中每个配置项都带有结构化 JSDoc 块包含name、type、default、version、description等标签例如 config.ts 中的/** * name server.port * type {number} * default 4321 * description * Set which port the dev server should listen on. * * If the given port is already in use, Astro will automatically try the next available port. */ port?: number;这些块的用户是配置astro.config.mjs的建站者描述的是配置契约本身绝不允许夹带内部实现说明比如某个内部归一化函数的行为细节——这正是该技能文档边界章节反复强调的反面案例。errors-data.ts的头部注释本身就是一条边界声明见 errors-data.ts// BEFORE ADDING AN ERROR: Please look at the README.md in this folder for general guidelines on writing error messages // Additionally, this code, much like types/public/config.ts, is used to generate documentation, so make sure to pass // your changes by our wonderful docs team before merging!文件内每条错误都按 README.md 的规范用docs、message、see、description标签组织例如UnknownCompilerErrorerrors-data.ts就是一个完整样例description从用户视角解释发生了什么、为什么、该怎么做而不是描述抛错逻辑的内部实现。读者的定义一个只有 HEAD 的陌生人规范把目标读者定义得非常具体一位精通 TypeScript、但完全没有你当前上下文的 Astro 贡献者——他看不到你这轮对话、看不到你的 PR、看不到关联 issue、也看不到你的 diff他只能看到仓库 HEAD 这一份代码。由这个前提直接推出两条铁律永远不要叙述变更历史。now现在、previously以前、no longer不再、the new approach新方案这类词在 HEAD 上毫无意义——那里只存在一种做法。注释要陈述代码如何工作而不是它如何演变而来。唯一的例外是deprecated声明见后文本仓库的惯例因为它描述的是契约的未来而读者确实需要知道。永远不要对评审者说话。注释不是用来论证我的改动是正确的——this properly handles X这正确处理了 X这类辩解属于 PR 描述不属于源码。注释必须为代码现状提供永久性辩护而不是为你的改动辩护。三类注释三件不同的事类型语法职责内容文件 / 模块概述文件顶部的/** */解释Explanation模块为什么存在、它定义的概念和术语、各部分如何关联、设计动因条目文档Item docs直接位于声明上方的/** */参考Reference契约行为、参数、返回值、抛出的错误、不变量。中性、事实性行内注释函数体内的//动机Rationale只有代码自己说不出来的东西约束、带 issue 链接的变通方案、不明显的耦合这三类职责严格分离对应 Diátaxis 文档框架中解释 / 参考 / 动机的三分法技能文档在 References 一节明确以此为理论来源。两个典型的混淆方向被点名禁止实现细节不属于/** */契约——应下沉为函数体内的//注释契约不应散落在行内注释里——应挂在声明上方的文档块上。行为文档为人类读者写契约而非翻译实现当一条声明确实需要条目文档时写作目标是给人类读者描述契约而不是把实现逐行翻译成文字。规范同时强调这并不意味着每个函数都要写 JSDoc——名称、类型和结构本身应当能承载直观行为承载不了就先改名字。具体写作要求先用一句通俗语言说明函数返回什么、完成了什么使用短句或中句每句只承载一个主要思想调用方不需要时避免内部术语Astro 黑话。确需使用技术术语就在同一段里解释描述调用方可见的、可能令人意外的注意点回退行为、工作量的上限、含糊的结果、重载的匹配顺序、副作用以及返回undefined、null、空结果或其他不确定值的条件当调用方需要区分或恢复时文档化抛出的错误除非调用方理解行为或安全使用 API 必须否则不描述实现细节。何时必须加示例当行为依赖于签名无法清晰表达的关系时应添加example。Astro 与 TypeScript 中最常见的五类场景哪个重载会被选中参数如何映射到可选参数或 rest 参数哪个公开的 Astro 入口点暴露了实现在别处的符号re-export 场景含糊路由、不完整配置或缺失内容时的回退行为含义无法从类型直接看出的返回值。示例的写法也有规范先用散文引出代码块说明它演示什么、预期结果是什么代码片段保持最小、自包含并且站在 Astro 用户或拥有该契约的内部调用方的视角书写。模块文档描述持久的概念模块级/** */应当描述一个持久的概念、架构边界或设计理由。禁止罗列文件中的各个导出项来总结文件——随着符号被增删改名这类清单很快就会过时stale。如果一个模块没有值得解释的持久概念那就写一行简短描述或者干脆不写概述。删除测试The Deletion Test写任何注释之前先问自己这条注释陈述的信息读者能否从代码本身恢复出来如果信息已经被名称、类型或结构承载就不要写注释如果名字承载不了去改进名字。真正有资格获得注释的信息一个不变量、一个动机、与别处代码的耦合、带链接的变通方案、某个依赖令人意外的行为、以及该模块定义的专业术语。编辑旧代码时同一测试反向适用不再通过的注释应当删除而不是留着慢慢腐烂。技能文档把这句收在自检清单的末尾并给出总基调删除是默认选项缺失的注释比误导性的注释更便宜。变通方案必须链接 issue 或 PR这是本仓库一条高度一致、可被机器核验的硬性规则**任何解释变通方案workaround、HACK、回归防护regression guard或依赖意外行为的注释必须链接到动机所在的 GitHub issue 或 PR。**链接的存在让未来的读者能判断这个变通方案是否仍然必要——技能文档的原话是没有链接的变通方案与一个错误无法区分。规范给出的标准示例// Handle recommended nanostores. Only nanostores/preact is required from our testing! // Full explanation and related bug report: https://github.com/withastro/astro/pull/3667 nanostores/preact,这条规则在仓库中并非纸上谈兵。packages/astro/src/vite-plugin-environment/index.ts 里的ALWAYS_NOEXTERNAL列表就是规范风格的活体样本每个条目都是一行理由 issue/PR 编号const ALWAYS_NOEXTERNAL [ // This is only because Vites native ESM doesnt resolve exports correctly. astro, // Vite fails on nested .astro imports without bundling astro/components, // Handle recommended nanostores. Only nanostores/preact is required from our testing! // Full explanation and related bug report: https://github.com/withastro/astro/pull/3667 nanostores/preact, // Must be bundled so the prerender output resolves Astros own copy, not an // older hoisted version from another dependency. See https://github.com/withastro/astro/issues/17508 neotraverse, ];注意其中的措辞都是现在时动机Vite fails on...、Must be bundled so...而不是我们改了它因为……式的历史叙述——恰好同时满足读者铁律和变通链接两条规则。七类被禁止的注释模式技能文档逐一点名并给出了改写对照这是全篇最具操作性的部分1. 复述下一行代码。看到就删// Increment the generation counter generation 1;2. 叙述变更历史。改写为现在时的动机说明// BAD: We now resolve lightningcss from the users root instead of ours. // GOOD: lightningcss is an optional peer dep, so it resolves from the users project root.3. 对评审者的辩解。论据移回 PR 描述// BAD: This correctly handles the multi-encoded path from the bug report. // GOOD: A path still encoded after MAX_DECODE_ITERATIONS is rejected, so // middleware and routing can never disagree on the decoded path.4. 换了个说法的 JSDoc。复述声明名的文档块等于没说// BAD: /** Compiles the styles. */ function compileStyles(...) // GOOD: /** Rewrites relative url() references in css against base, leaving * absolute and data URLs untouched. */ function compileSkills(...)注意示例中 GOOD 版本说明了行为契约——重写相对url()、不动绝对与 data URL——而不是翻译函数名。5. 含糊的套话。some cases、various reasons、handles edge cases、etc.——要么点名具体是什么要么删掉整句。6. Emoji。源码中全面禁用注释也不例外这是仓库级政策。7. 临时分区横幅如// ----- helpers -----、// TYPES 。本仓库没有// #region折叠惯例不要添加横幅。如果一个文件长到你伸手去找横幅那是该拆分文件的信号不是该装饰它的信号。本仓库的注释惯例以下惯例是 Astro 源码特有的约定脱离仓库语境可能不成立JSDoc 标签。param name - description、returns、throws用于陈述契约只有当签名本身有歧义时才用花括号包裹类型如returns {Promisestring}非显而易见的用法配example加js围栏代码块。交叉引用。使用{link Symbol}/{linkcode Symbol}而不是裸写符号名这样符号改名时引用会自动更新编辑器也能跳转到目标。internal。标记不属于公开 API 面的符号。它只是约定——这个仓库没有 typedoc 或 api-extractor 来剥离它——所以它表达的是意图不能替代真正的访问控制手段。deprecated。先说迁移方案再说移除时间点仓库示例/** deprecated Use the instance method cookies.consume() instead. This will be removed in Astro 7 */关键是说替代方案是什么而不只是此符号已废弃。这条面向未来的陈述属于读者需要的契约信息不属于被禁止的历史叙述——这正是读者铁律第 1 条预留的例外通道。TODO。延后工作用// TODO:有 issue 跟踪就附链接受破坏性变更窗口约束的工作使用既定句式// TODO: remove in Astro N。本仓库不存在FIXME——不要引入它。这句约定在源码中有直接证据例如 packages/astro/src/content/runtime.ts 中的两处// TODO: remove in Astro 8 warnForPropertyAccess( logger, result.data, slug, [content] Attempted to access deprecated property on ${collection} entry.\nThe slug property is no longer automatically added to entries. Please use the id property instead., );这里的措辞细节值得品味TODO 本体只说在 Astro 8 移除而给用户看的警告字符串才解释替代路径——两条信息各归其位互不污染。编辑已有代码时的三条纪律保留既有注释。如果你的改动改变了行为就扩展或修正对应的那段散文——绝不替换成通用套话。删除来之不易的上下文比留一条略微过时的注释更糟。注释被你的改动说假了就在同一个 diff 里修好。过时的注释比没有注释更坏。匹配周边的注释密度。文档密集的模块新增条目应达到同等水准也不要给本来就稀疏的模块泼一身注释。收尾自检只重读 diff 里的注释技能文档要求完成任何触碰注释的任务后把 diff 中新增的注释单独摘出来、脱离代码改动重读一遍逐条过四问每一条是否通过删除测试是否有引用对话、引用本次改动本身、或对评审者说话的每个变通方案是否链接了它的 issue 或 PR一个看不到 diff 的读者能否独立理解每一条不达标的修掉或删掉。删除是默认选项。自动化评估规则如何被验证这些规范并非仅靠人工评审执行。仓库中 .agents/skills/writing-comments/evals/evals.json 为写作注释技能定义了三个可断言的评估场景恰好覆盖规范的核心分支变通场景给定一段无上下文的resolveLightningcss源码要求补注释。断言包括注释必须位于函数体内//而非声明 JSDoc、必须说明lightningcss 是可选 peer dependency、须从用户项目根解析、必须包含追踪 issue 的准确 URL、禁止出现叙述 import/return 的行、禁止now/previously/correctly handles等历史或辩解措辞、禁止 emoji 与横幅。契约场景给定resolveEntry(collection, slug)精确匹配 → 回退 →undefined的语义无法从签名看出要求补写完整条目 JSDoc。断言包括开头散文描述调用方可见的结果而非复述函数名、JSDoc 覆盖精确匹配/回退/返回undefined三种条件、包含param collection -、param slug -、returns、带js围栏代码块的example、且不得宣称函数会抛错、不得谈论Map.get等实现细节。边界场景要求把一段normalizeAssets()的内部实现动机写进types/public/config.ts的docs块——正确行为是拒绝修改识别出docs块属于生成的用户文档、不在贡献者注释规则管辖内且需要遵循 errors/README.md 一类的仓库指引并取得 docs 团队评审。这三个场景与本技能规范文档.agents/skills/writing-comments/SKILL.md构成规范—验证闭环凡你在 Astro 中写下的注释都可以用同样的断言清单自测。参考规范本体.agents/skills/writing-comments/SKILL.md评估用例evals.json用户文档边界packages/astro/src/core/errors/README.md、packages/astro/src/types/public/config.ts、packages/astro/src/core/errors/errors-data.ts规范风格实证packages/astro/src/vite-plugin-environment/index.ts、packages/astro/src/content/runtime.ts理论来源技能文档 References 一节引用Diátaxis 框架解释 / 参考 / 动机三分法、TSDoc 标签规范【免费下载链接】astroThe web framework for content-driven websites. ⭐️ Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/as/astro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考