为 Remix 开源项目撰写技术指南write-guides 技能实战手册【免费下载链接】remixThe fully-stacked web framework项目地址: https://gitcode.com/GitHub_Trending/re/remix导读write-guides是 Remix 仓库docs/guides/app/actions/docs/chapters/ 指南目录内置的一项写作技能它定义了撰写、改写与审计 Remix 指南章节的完整规范从像人一样讲解真实 Remix 代码的语气基准到识别并消除 AI 腔调的反模式清单再到教程、概念章节、代码示例、锚点链接的编排原则与可执行的审计/重写工作流。读完本文你将掌握一套可直接复用的技术文档写作方法论并理解其背后对应的仓库章节文件与源码实现能够独立为 Remix 或其他开源框架撰写风格统一、事实准确、便于 Agent 与 LLM 理解的技术指南。技能定位为谁写、写什么技能文档.agents/skills/write-guides/SKILL.md开篇即说明用途编写、重写或审计 Remix 指南章节语气以 01-start-here.md 为基准典型工作对象是docs/guides/app/actions/docs/chapters/*.md。其核心写作目标是让指南读起来像一个人走在真实的 Remix 代码里具体指向真实的文件、URL、路由、处理器、组件与响应直接少铺垫、少复述快速进入代码略带对话感用我们走完步骤、你做选择谨慎对待示例示例必须能跑不能为修辞牺牲准确性避免空洞修饰拒绝放之四海而皆准的抽象表述。仓库中的实际章节正是这一标准的产物。以 01-start-here.md 为例它用一个数字唱片店albums record store贯穿全章定义路由、渲染首屏、提交表单、水合组件每一步都给出可运行的代码片段与可访问的本地 URLhttp://localhost:44100。写作前的必读清单动手编辑任何指南章节之前技能文档要求按顺序完成以下阅读通读 01-start-here.md把握语气与示例风格基准完整阅读目标章节不得只看片段阅读相邻章节——当目标章节引用更早或更晚的概念时上下文必须连贯若章节涉及 Remix 应用代码先加载remix技能或相关参考再构思模式禁止凭空发明若任务仅是识别AI 味的散文则报告带行号的发现除非被明确要求否则不做修改。这套流程在仓库中可以得到验证01 章结尾明确预告Next, Routing and Controllers takes a closer look at the route leaves, nested maps, and controllers而 02 章开头反向回指 In Chapter 1we built one end-to-end request flow相邻章节正是通过这种互相引用的方式保证读者始终有完整上下文。语气基准像人一样讲解代码从读者刚做过的事出发章节开头应从读者刚刚完成或即将进行的操作切入而不是抛出抽象论点。指南正文允许在第一个小节前有一段简短的前言来划定范围说明本章覆盖什么、处于请求路径的哪个位置。但底线是必须点名具体的文件、API 或阶段——比如 01 章的前言点出定义路由、返回服务端渲染页面、处理表单提交、水合一个组件而不是一句能套在任何框架头上的泛泛之词。用词与人称技能文档给出的三个范例极有代表性Back in routes.ts, add the edit route with form(...).Since albums.edit is a nested route map, give it its own controller.Open /albums/thriller/edit. The route now returns an HTML form with the album data filled in.可以看到人称上**我们用于走查步骤、你用于读者可控制的决策**段落保持短小一个段落通常只讲一个观点展示代码后立即解释但不必逐行解说能用示例承载解释就让示例来承载密集的事实文件职责、路由展开、上下文字段用小号列表呈现。章节引言可以更论文化小节开头必须务实技能文档特别强调一条界限章节级引言可以适当声明范围相对更像论文主题句但小节开头必须收窄直接进入具体工作。01 章用六大原则与What is Remix?完成了章节级引言而其下每个##小节都以Define your first routeBuild your first page这类动作句开场直接落到app/routes.ts、app/actions/albums/controller.tsx这些具体文件上。反 AI 腔调模式清单技能文档列出需要删改的AI 味特征这是整套规范中最具操作性的部分具体工作开始前先来一句抽象主题句章节引言除外通用化表述如 doing real work、seamlessly、robust、powerful、unlock、designed to make it easyone source of truth——除非该段立刻给出精确的类型值并说明它变化时会破坏什么在示例前后重复同一个观点断奏式解释——连续多个短句逐一解释相邻且显而易见的部件应合并为更自然的表达把分号当散文标点使用代码片段除外代码遵循本地 Prettier 配置软过渡词如 Additionally、Furthermore、It is important to note、A few things to keep in mind、This is where X comes in占位名词——有精确名词时不用 thing、stuff、pieces、functionality过度自信的安抚如 TypeScript tells you every place 或 the failure is loud——要说实际会发生什么任何框架指南都能写的通用 Web 建议结尾段落只是复述本节而非推动读者前进。技能文档给出了正反对照推荐写法Remix checks this during router setup. If a controller is missing an action for a leaf it owns, setup throws before the app starts serving requests.避免写法This keeps ownership explicit and makes failures loud, ensuring your app stays in sync as it grows.前者陈述可验证的事实与后果后者是空洞的修辞包装。这一原则也贯穿仓库源码例如router.map(routes, controller)这类 API 在 01-start-here.md 中被直接展示——For now theshowaction returns a plain WebResponse——用代码与结果说话而不是用形容词担保。结构编排教学顺序优先于 API 顺序技能文档的核心主张是教学法重排pedagogical reordering指南引入概念的顺序应以帮读者建立心智模型为准而非 API 参考文档的罗列顺序。通用原则保留 frontmatter 的 title 与 description除非章节范围变更保留已被其他章节链接的显式标题锚点每个小节用最小必要的上下文开场学习顺序先具体形状、再便捷写法、最后边界情况展示高级能力时优先看我做到了什么的示例而不是逐特性的慢速巡礼当代码本身就是被解释的对象时先展示代码再长篇解释把相关解释紧贴在代码或列表旁边小节结尾指向下一个实际细节而不是复述论点。指南章节Guide Chapters的进阶规则技能文档强调先教显式形状再引入便捷 helper。例如在讲get(...)、post(...)、form(...)之前先展示一个完整的{ method, pattern }路由对象让叶子、分支与生成的 helper 更容易理解。这一顺序在仓库的 02-routing-and-controllers.md 中得到严格执行该章先给出手写对象形式的 route mapshow: { method: GET, pattern: /albums/:albumId }再讲get/post/form等构建函数最后才谈边界情况与完整语法。指南还必须与 API 概览保持距离只教授读者理解本章所需的语法面用一个强示例展示高级用法的力量然后把完整语法或穷尽细节链接到 API 概览避免在指南内逐特性复刻参考文档。教程Tutorials的节奏教程遵循下一步行动节奏说明读者下一步要构建或改动什么给出文件路径与命令或代码解释改变了什么、如何看到效果只在读者已有足够本地上下文后才提及相关章节。01 章的Build your first form action一节正是此模板先Back inroutes.ts, use theform()route helper再给出mkdir app/actions/albums/edit与touch ... controller.tsx page.tsx随后解释form(/albums/:albumId/edit)生成了routes.albums.edit.indexGET与routes.albums.edit.actionPOST两条路由最后引导Open http://localhost:44100/albums/thriller/edit. The route returns an HTML form。概念章节Concept Chapters概念章节从具体应用表面出发文件、导入、函数、路由映射、响应尽量使用一个贯穿全章的运行示例优先展示最显式的形式再讲别名与快捷生成直接教常见情况、把高级情况压缩成紧凑列表或一个有表现力的示例并先命名规则、再用代码展示后果比较相关部件时用短表格或项目符号而非并排的平行段落。代码示例规范针对docs/guides/app/actions/docs/chapters/下的示例技能文档有明确的格式要求从remix/...导入而不是remix-run/...——这与仓库实际的包结构一致packages/remix/src 中所有子路径remix/router、remix/routes、remix/ui、remix/middleware/render、remix/data-schema等均由单一remix包导出让本地章节格式化配置处理代码格式——docs/guides/app/actions/docs/chapters/.oxfmtrc.json特意使用双引号而非仓库 TypeScript 风格不要手工把片段改回仓库风格仓库根 package.json 中的format脚本为oxfmt . --writeformat:check为oxfmt . --check相对导入使用 TypeScript 文件扩展名如../../routes.ts片段内部必须自洽用到的 helper 都有导入、无用导入被移除、命名与周边示例一致优先沿用现有的 albums 唱片店示例除非章节确实需要不同领域使用routes.name.href(...)生成链接、重定向、表单与测试中的 URLaction 返回显式的 WebResponse对象示例保持足够真实可直接复制、足够短小便于看清要点若片段省略了周边代码用简短注释标注如// inside an action:不要假装是完整文件。这些约束在 01-start-here.md 的示例中逐条可见import { createController } from remix/router、import { routes } from ../../routes.ts、routes.albums.edit.action.href({ albumId: album.id })、return redirect(routes.albums.show.href({ albumId: album.id }), 303)以及// Simulate network latency这类标注式注释。锚点与链接管理默认使用生成的标题锚点仅当需要保留既有链接锚点、或有意选择与生成值不同的锚点时才添加显式{#anchor}移除仅重复生成锚点的显式锚点修改或移除标题锚点前先用rg #anchor-name guides packages搜索入站链接当其他章节链接到旧锚点时即使简化了标题文本也要保留旧锚点——01 章的## Quickstart: create and run a Remix app {#quickstart}与## Define your first route {#define-your-first-route}正是显式锚点与标题并存的实例同文档内锚点可以保持相对跨章节文档链接使用指南既有的/docs/...风格不要给每个小节都加上更多信息式的链接堆砌结尾当指南有意跳过穷尽的语法、选项或包面时链接到 API 概览。AI 散文审计工作流当被要求识别生成腔散文时按以下六步操作读取文件并获取行号按模式分组发现而不是逐句罗列引用触发疑虑的短短语原文解释为什么该短语读起来像生成的给出改写方向的建议——除非被明确要求否则不重写整个文件指出具体错误缺失导入、无用导入、标题不匹配、过期锚点、无法编译的示例。审计工作流要求给出行号这与技能文档Read First阶段的第 5 条报告带行号的发现互相呼应保证审计结果可复核、可追踪。重写工作流当任务升级为重写时按以下顺序执行保留有价值的技术内容与示例移除重复的结论与通用过渡句用具体讨论中的文件、API、路由或响应替换抽象框架当现有顺序先教快捷写法、后教底层形状时重排章节与示例在改写散文的同时修正示例漂移example drift——即示例与前后文不一致的问题对照 01-start-here.md 重读章节抚平语气偏差对改动的 Markdown 文件运行 Prettier 校验pnpm exec prettier --check path-to-chapter.md仅当格式变更符合预期且可接受时才使用pnpm exec prettier --write path-to-chapter.md。注意第 4 条与结构编排的原则一脉相承如果当前顺序先教了form(...)这种便捷写法、还没教底层的{ method, pattern }形状就应该重排让读者先建立底层模型。评审清单交付前的最后一道闸技能文档以一份可勾选的评审清单收尾这也是每篇指南合并前的验收标准章节读起来是否像 01-start-here.md 的延续首段是否以有用上下文开场而非通用论点是否删除了重复的write once / stay in sync / TypeScript catches it式结论除非每一条都新增信息所有代码片段是否内部自洽顺序是否先教底层形状、再教快捷 helper 与边界情况是否在避免重复 API 概览材料的同时仍展示了底层 API 的价值章节内的路由名、参数、导入与文件路径是否一致是否保留了其他文档链接到的锚点链接用于真实下一步而非填充式结尾改动的 Markdown 是否通过了 Prettier 检查这份清单同时服务于人与机器读者对开发者它保证指南可复制、可运行、可定位对 Agent 与 LLM它保证章节内的事实、路径与代码互相印证从而可以被安全地检索与引用。与仓库生态的对应关系这套写作规范并非孤立的文档礼仪而是与仓库的实际结构深度咬合语气基准文件01-start-here.md六大原则、Quickstart、albums 贯穿示例章节目录docs/guides/app/actions/docs/chapters/ 下共 17 个章节从 02-routing-and-controllers.md路由映射与构建函数到 15-production.md生产部署每章遵循同一套语气与结构规范源码佐证示例中反复出现的clientEntry(import.meta.url, ...)对应 packages/ui/src/runtime/client-entries.ts 的实现——clientEntry(entryId: string, component)接收模块 URL 与组件函数createController/createRouter来自remix/router子路径packages/remix/srcformData()中间件来自remix/middleware/form-datacreateRequestListener适配 Fetch handler 到http.createServer见 03-request-handling.md 的server.ts示例格式化配置.oxfmtrc.json章节片段双引号约定、仓库根 package.json 的format/format:check脚本oxfmt示例领域一致性albums 唱片店示例贯穿 01/02/03/13 等多个章节技能文档要求优先沿用现有 albums 示例正是为了维持整部指南示例域的统一降低读者跨章节理解成本。掌握了write-guides的这套方法论你既能产出风格统一、可运行可验证的 Remix 指南章节也能以同样的标准审计既有文档——无论是为开源项目贡献文档、为团队建立写作规范还是训练 Agent 生成更可信的技术内容这套具体、直接、以代码为准的原则都值得直接套用。【免费下载链接】remixThe fully-stacked web framework项目地址: https://gitcode.com/GitHub_Trending/re/remix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考