用途：规范在 Go html/template 上使用 htmx 的工程实践，核心原则是服务端持有状态、模板只负责呈现、htmx 在两者之间搬运 HTML，避免每个 handler 和模板各自临时决定请求与响应形态的漂移。
主要规则与能力：htmx 请求头统一走一套 helper 常量与断言，不手写字符串；每条路由在一处声明响应形态（页面、片段或重定向）；同一 URL 可能返回页面或片段时设置 Vary: HX-Request；历史恢复请求（HX-History-Restore-Request: true）始终返回完整页面；非 htmx 表单 POST 以 303 跳转到 GET，htmx 请求则以 HX-Location 或片段回应；表单在无 JavaScript 下可用，htmx 属性叠加其上；重复的属性组合抽成命名 {{define}} 片段；轮询用 hx-sync 并加守卫，避免与用户输入冲突；错误要送达用户，htmx 2.x 默认不交换 4xx/5xx 响应体，需配置 responseHandling 交换所用状态码（通常 422）并用 HX-Retarget / HX-Reswap 落到持久的 aria-live 区域；提交控件加 hx-disabled-elt 防重复提交，替换区域用 hx-indicator 或 aria-busy 显示进行中状态；客户端 JS 为例外且不得内联，优先用服务端或原生 HTML（details、dialog、popover），确需客户端状态时做成前端框架中的孤岛，通过 htmx.onLoad 挂载、交换时卸载，htmx 配置放在 <meta name="htmx-config"> 并设 "allowEval": false；模板只做呈现分支，领域逻辑在 Go 中算成视图模型字段。
使用方式：按工作内容查阅对应参考文件——handler 相关（响应形态、htmx 头、Vary、303、错误响应）见 references/responses.md；模板相关（片段、属性组合、表单、live region、条件）见 references/templates.md；客户端 JS 相关见 references/client.md。仓库自身信息（交换目标 id、共享片段名、内置 htmx 版本）需先读仓库的 AGENTS.md。
注意事项：不要把错误路由交给 response-targets 扩展；不要用 outerHTML 交换 aria-live 区域，应交换其 innerHTML；不要直接渲染进 ResponseWriter，先渲染到缓冲区，使模板错误变成 500 而非写出一半的 200；不要用 hx-boost 修补导航问题；不要重复罗列 htmx 属性参考，直接链接 htmx.org/reference。这些规则针对 htmx 2.x，若仓库使用 4.x 需按迁移说明重新核对错误响应与属性继承相关规则。