clickhouse-best-practices

修复 clickhouse-best-practices 中的版本 (#31) 已更新以匹配实际技能中的版本

docs(best-practices)：在 avoid-update 规则中提及轻量级 UPDATE (#27) https://github.com/ClickHouse/agent-skills/issues/26 ## 摘要 - 重构 `avoid ALTER TABLE UPDATE` 规则，使其与 `avoid ALTER TABLE DELETE` 规则保持一致 - 在 ReplacingMergeTree 之外，新增轻量级 UPDATE（25.7+）替代方案 - 新增更新策略对比表 ## 测试计划 - [ ] 渲染该规则并确认格式与 `insert-mutation-avoid-delete.md` 一致 🤖 使用 [Claude Code](https://claude.com/claude-code) 生成 Co-authored-by: Claude Opus 4.7 (1M context)

新增 agent 连接与查询工作流规则 (#23) ## 摘要 新增 6 条规则（共 28 → 34 条），涵盖 AI agent 应如何连接、 发现并安全查询 ClickHouse。 **动机：** 客户反馈称将 AI agent 连接到 ClickHouse“需要相当多的提示才能正确配置连接和 凭据”。现有技能涵盖 schema/查询/插入最佳 实践，但没有针对 agent 的工作流指导。 ### 新规则 | 规则 | 影响 | 覆盖范围 | |------|--------|----------| | `agent-connect-mcp` | HIGH | 自托管 + Cloud MCP 服务器设置、 凭据发现 | | `agent-connect-cli` | HIGH | `clickhouse-client` 标志、格式 选项、性能 | | `agent-connect-http` | MEDIUM | 用于 lambda/程序化访问的 HTTP 接口 | | `agent-discovery-schema` | CRITICAL | 7 步 schema 发现 （数据库 → 表 → 列 → 排序键 → 跳数索引 → 采样 → EXPLAIN） | | `agent-query-safety` | CRITICAL | LIMIT、超时、渐进式 探索、EXPLAIN ESTIMATE | | `agent-format-selection` | HIGH | JSON vs JSONEachRow vs TSV — token 效率 | ### 关键新增内容 - **在哪里找到凭据**：ClickHouse Cloud 控制台的分步说明 - **列注释**：关于使用 `system.columns` 注释进行 语义理解的指导 - **跳数索引发现**：查询前检查 `system.data_skipping_indices` - **EXPLAIN 验证**：在执行 高开销查询前验证查询计划 - **MCP vs CLI 性能权衡**：何时使用每种方法 ### Agent 查询工作流 每个 agent 会话都应遵循：连接 → 发现 → 规划 → 验证 → 执行 → 校验 ---------

fix：修正 join_use_nulls 默认值（0，而非 1） (#20) ## 摘要 `query-join-null-handling.md` 中的表格错误地将 `join_use_nulls = 1` 标记为默认值。实际默认值是 `0`（false）。 ## 证据 **ClickHouse 源代码** ([`Settings.cpp#L2305`](https://github.com/ClickHouse/ClickHouse/blob/4d79f6ea35f896060e55128fe8ca4216f455d9c0/src/Core/Settings.cpp#L2305))： ```cpp DECLARE(Bool, join_use_nulls, false, ...) ``` **已在 ClickHouse Cloud 实例上验证：** ```sql SELECT name, value, changed FROM system.settings WHERE name = 'join_use_nulls' -- value=0, changed=0 ``` ## 为什么这很重要 在 `join_use_nulls = 0`（实际默认值）下，LEFT JOIN 未匹配时 返回该类型的默认值（String 为 `''`，Int 为 `0`）——而不是 NULL。使用 `IS NOT NULL` 来检测匹配的代码会静默地 始终返回 true。 ## 变更 在“何时使用”表格中，将 `(default)` 标签 从 `join_use_nulls = 1` 改为 `join_use_nulls = 0`。

更新 ClickHouse 技能的安装命令 (#10) 旧方法已弃用。

feat：新增 28 条 ClickHouse 最佳实践规则并改进文档 (#2) ## 摘要 - 新增 28 条原子规则，涵盖 schema 设计、查询优化和 数据摄取最佳实践 - 改进 README，使其结构更清晰，包含技能概览表和 快速入门指南 - 按类别和影响级别（CRITICAL、HIGH、MEDIUM）组织规则 ## 新增规则 | 类别 | 规则数 | 影响 | |----------|-------|--------| | 主键选择 | 4 | CRITICAL | | 数据类型选择 | 5 | CRITICAL | | JOIN 优化 | 5 | CRITICAL | | 插入批处理 | 1 | CRITICAL | | 避免 Mutation | 2 | CRITICAL | | 分区策略 | 4 | HIGH | | 跳数索引 | 1 | HIGH | | 物化视图 | 2 | HIGH | | 异步插入 | 2 | HIGH | | 避免 OPTIMIZE | 1 | HIGH | | JSON 使用 | 1 | MEDIUM | ## 测试计划 - [ ] 验证所有规则文件均遵循模板格式 - [ ] 确认 AGENTS.md 已正确生成 - [ ] 检查所有内部链接均可正确解析 🤖 使用 [Claude Code](https://claude.com/claude-code) 生成 --------- Co-authored-by: Doneyli De Jesus Co-authored-by: Claude Opus 4.5

chore(setup)：新增仓库结构 (#1)