ChuSQL/AGENTS.md

AGENTS.md — ChuSQL 开发契约

参考：

• 唯一进度与验收来源：.agents/context/progress.txt（等价于 project-plan.txt）。
• 限制与设计：.agents/context/known-issues.txt、.agents/context/design-decisions.txt。

核心约束

• 测试必须通过，禁止绕过检查。
• 不吞错误，使用明确错误返回。
• FFI 响应由 Rust 分配并通过配套 free 归还；句柄关闭不得与请求并发。
• 表存在性以 catalog 为准。
• 语义检查和优化只使用 schema。
• 索引由存储层管理，优化器只判断可点查条件。
• 优化不能改变结果语义。
• 持久化、事务、并发、类型及 FFI 改动优先维护不变量、内存所有权与错误传播；保留必要的迁移和恢复约束。

开发方式

• 按任务选择已安装 Skills：编码用 ponytail / karpathy-guidelines，审查与简化按需用 ponytail-review；Rust、FFI、测试及覆盖率分别使用对应项目技能。

• 类型、值、转换或表达式语义用 chusql-type-system；存储、序列化、系统目录、初始化或恢复用 chusql-storage-integrity；FFI、跨组件协议、序列化契约或外部接口用 chusql-boundary-contracts（均在 .agents/skills/）。

• 跨领域组合相关 Skills，无关任务不加载；Skills 不覆盖更高优先级的安全和工程约束。

• 简单任务直接执行；采用最小必要改动，允许有明确收益且能验证的局部结构优化，优先删除重复和无用代码。

• 保持代码最简：用最少且易读的代码完整解决当前需求，优先复用现有实现与标准库；相同规则只维护一份，不引入仅为缩短函数或预留未来而存在的抽象、包装、配置和依赖。简化须保持求值顺序、错误传播、边界校验及恢复约束，不以压缩行数牺牲清晰度或正确性。

• Haskell 编码后对受影响源码运行 HLint（与 nvim 的提示来源一致），修复能保持语义的建议；不通过禁用提示绕过检查。

  优先使用 void、when/unless、fromMaybe、isJust/isNothing、maybeToList、zipWithM 等惯用函数，避免冗余 lambda、括号、绑定、导入与 LANGUAGE pragma；涉及惰性、严格性或类型表示变化的建议须核对语义，不能机械套用。

• 测试强度与实际风险及影响范围匹配，不机械新增测试，不盲目追求覆盖率；数据库内核微改动也须验证关键行为。

• 不强制 TDD、子代理或多阶段审查；减少无关读取、重复搜索、工具调用和输出，Skills 不应增加无收益的流程。

• 文档描述当前状态；不创建整改报告、修改流水账或无用途的兼容层，不修改 Git 历史。

文档编写

编写、修改或审阅 README、docs/ 及其他说明文档时，加载以下全局 Skills：

• technical-documentation：先确定读者和阅读目的，再安排标题、操作步骤、示例与参考信息。入口为 ~/.codex/skills/technical-documentation/SKILL.md。
• plain-writing：用常用词解释行为，删除空话，拆开堆叠的术语与长句。入口为 ~/.codex/skills/plain-writing/SKILL.md。

涉及设计理由时，另用 documentation-and-adrs，沿用现有设计文件，不另建决策或进度来源。全局目录以 $CODEX_HOME/skills 为准，未设置时使用 ~/.codex/skills。

文档须遵守以下约定，中文不机械套用英文语法规则：

• 开头说明本页帮助谁完成什么任务。README 先帮助安装和使用，内部实现放在架构文档中，通过链接提供深入阅读。
• 按问题或任务分节，每段只解释一个主题，通常用 2 至 4 句。长段落优先拆分主题，不把整页改成零碎列表。
• 有先后顺序的操作用编号步骤，并说明前提和验证结果；并列要点用列表；参数和能力对比用表格。标题、正文、列表和代码块之间留空行。
• 必要术语首次出现时用一句中文解释，再保留准确名称。同一概念使用同一名称，不连续堆叠缩写、内部类型和函数名。
• 命令和示例标明语言及占位符含义。链接文字说明目标内容，图示须有正文说明，不让关键信息只存在于图中。
• 完稿后按读者顺序通读，核对链接、命令、条件、错误行为和限制。排版与措辞优化不得删掉技术边界，不为简化表达夸大能力；规划与已实现能力分开说明。

注释规范

• 文件级：外部引用语句（Haskell import、Rust use、JS import、HTML 的 <link>/<script>、 CSS @import、脚本的依赖/参数区）之后写一段注释，概括本文件的功能；没有引用语句的文件写在 文件开头。长度不超过 3 行、合计不超过 90 字。
• 函数级：每个函数（含 Haskell 的 where/let 内函数、Rust 的私有 fn）前用一行不超过 30 字的注释说明它做什么。
• 摘要说明做什么；仅在必要处补充不直观的不变量、所有权与安全约束，不记录历史和被删实现。

协作规则

• 全量门禁入口：gate-check/run-gate.ps1（三条车道并行，日志写仓库根的 logs/）。
• 局部改动运行受影响模块的规定测试；较大改动由 agent 执行全量门禁，通过后再提交。
• engine / web / storage 使用规定测试入口。
• 规定入口见 gate-check/run-step.ps1；Haskell 构建串行，存储协议改动须重建实际动态库。
• 改动说明只在交流中记录。