# 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 构建串行，存储协议改动须重建实际动态库。
- 改动说明只在交流中记录。