| name | hop |
| description | 在项目的任何阶段加载并始终生效：架构设计、制定计划、编写代码、重构优化、代码审查、补注释、调试修复、测试验证、文件整理、性能优化、安全检查、文档撰写。确保所有代码产出始终遵循 HOP（面向人类编程）思想：高密度精华注释、触发-指令-数据-反馈架构主线、局部可读性优先、commands/store/tools 职责分离、数据流显式可追踪。当提到 HOP、面向人类编程、human-oriented programming、代码可读性、注释密度、注释规范、架构规范、命名规范、代码审查、代码风格、项目结构设计、初学者友好、代码即文档、可维护性时触发。 |
HOP —— 面向人类编程规范
本规范是项目的最高工程准则。所有代码产出、重构决策、审查判断必须以本规范为唯一衡量标准。偏离即纠正，无例外。
核心目标
让任何人——包括刚学编程的初学者——只看局部代码就能理解这段代码在做什么、为什么这么做、数据从哪来到哪去、能怎么改。代码即文档，注释即教材，命名即说明书。不依赖任何背景知识，不需要记住项目架构和历史。
架构主线
一切交互与业务流程必须按以下链条组织，不允许例外：
触发事件 → 指令执行 → 数据修改 → 效果反馈
详细说明与分层规则参见 references/architecture.md。
命名准则
用业务对象命名，禁止技术术语。缩写整体保留，不拆不变形。
详细规则与示例参见 references/naming.md。
注释准则
注释是本规范的核心竞争力。目的不是解释难点，而是让初学者连续顺畅地阅读代码，像读教材一样理解每一步。
详细规则、密度要求与格式标准参见 references/comments.md。
函数结构
固定顺序：函数段落标题 → 函数头（含参数注释）→ 卫语句（每条加注释说明原因）→ 空行 → 主逻辑（读取数据/处理逻辑/修改数据）→ 反馈/返回结果。
- 甜区：4–16 行。超出优先拆分，但小逻辑优先就地写保持阅读不断。
- 只有当一块逻辑已形成独立语义、拆出后更容易理解时才拆。禁止拆成少于 3 行或只用一次的碎片函数。
- 指令函数职责单一，一个指令只完成一个清晰业务动作。指令之间通过组合而非嵌套实现复杂功能。
- 连续的单行操作应每行配备尾随注释，紧凑排列形成操作步骤清单，让整个函数读起来像一份带解说的流程图。
代码组织
- 按自然动作分段，不同语义段之间留空行，同一语义段紧凑排列。
- 每个函数之间空 2 行。
- 复用规则：第一次出现就地写清楚；稳定出现两次及以上再提取。禁止提前为可能复用而抽象。
- 数据流必须显式可追踪：局部代码必须自带足够上下文，让人只看这一小段也能知道数据被读、被改、被返回、被影响。
正反对比
以下文件展示了同一功能的正确写法与错误写法，供生成和审查时参照：
生成后自查
每次生成或修改代码后，必须对照以下清单逐条确认。任何一条未通过，立即修正后再输出：
- 架构主线是否清晰？能否从入口顺着链条追踪到指令、数据、反馈？
- 命名是否使用业务对象？是否混入了技术术语或抽象概念？
- 注释密度是否足够？是否存在连续超过 2 行的裸代码？import、export、模块变量是否都有注释？
- 注释格式是否正确？尾随注释是否对齐？是否使用了段落标题分隔？是否避免了标注式注释格式？
- 文件职责是否单一？是否存在入口做业务、指令操作 UI、工具混入业务的情况？
- 数据流是否显式？是否存在隐式传递、全局变量滥用、追踪困难的数据？
- 模块是否具备独立性？能否被单独理解、单独移除或替换？是否存在隐式耦合？
- 副作用是否集中管理？是否散落在各处难以追踪？
- 与 examples/correct.js 风格对比，视觉节奏是否一致？
发现偏离时：指出偏离点，给出最小修正方案，执行修正。不妥协，不搁置。
