topfans/CLAUDE.md at b38174917a2596d89b06ed7769a333adc17d6da7

zheng020 071bcca237 feat:修改claude规则文档

2026-06-12 16:59:15 +08:00

6.9 KiB

Raw Blame History

MCP Tools: code-review-graph

IMPORTANT: This project has a knowledge graph. ALWAYS use the code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore the codebase. The graph is faster, cheaper (fewer tokens), and gives you structural context (callers, dependents, test coverage) that file scanning cannot.

When to use graph tools FIRST

Exploring code: semantic_search_nodes or query_graph instead of Grep
Understanding impact: get_impact_radius instead of manually tracing imports
Code review: detect_changes + get_review_context instead of reading entire files
Finding relationships: query_graph with callers_of/callees_of/imports_of/tests_for
Architecture questions: get_architecture_overview + list_communities

Fall back to Grep/Glob/Read only when the graph doesn't cover what you need.

Key Tools

Tool	Use when
`detect_changes`	Reviewing code changes — gives risk-scored analysis
`get_review_context`	Need source snippets for review — token-efficient
`get_impact_radius`	Understanding blast radius of a change
`get_affected_flows`	Finding which execution paths are impacted
`query_graph`	Tracing callers, callees, imports, tests, dependencies
`semantic_search_nodes`	Finding functions/classes by name or keyword
`get_architecture_overview`	Understanding high-level codebase structure
`refactor_tool`	Planning renames, finding dead code

Workflow

The graph auto-updates on file changes (via hooks).
Use detect_changes for code review.
Use get_affected_flows to understand impact.
Use query_graph pattern="tests_for" to check coverage.

数据库操作规范

PostgreSQL 序列同步规则（强制）

问题背景：项目使用 BIGSERIAL / autoIncrement 自增主键。当通过 SQL 手动 INSERT 指定 id 值时，PostgreSQL 序列不会自动跟进，导致后续 GORM 插入报 duplicate key value violates unique constraint。

触发场景：

测试数据脚本（如 create_gallery_test_users.go）硬编码 ID
数据迁移脚本手动插入记录
DBeaver / psql 手动补数据

规范要求：

任何手动指定 ID 的 INSERT 语句，末尾必须同步重置序列：

-- 错误示例（会导致序列不同步）
INSERT INTO assets (id, name, ...) VALUES (1000, 'xxx', ...);

-- 正确示例
INSERT INTO assets (id, name, ...) VALUES (1000, 'xxx', ...);
SELECT setval('assets_id_seq', (SELECT MAX(id) FROM assets));

脚本文件规范：所有输出 SQL 的 Go 脚本（如 backend/scripts/*.go），必须在生成的 SQL 末尾包含序列重置语句：
```
fmt.Printf(`SELECT setval('%s_id_seq', (SELECT MAX(id) FROM %s));\n`, tableName, tableName)
```
新表创建时：预留足够的序列起始值给测试数据：
```
CREATE SEQUENCE assets_id_seq START WITH 10000;
```

定期检查：环境部署后执行以下 SQL 确认序列健康：

SELECT 
    schemaname, sequencename, last_value,
    (SELECT MAX(id) FROM assets) AS table_max_id,
    last_value >= (SELECT MAX(id) FROM assets) AS is_healthy
FROM pg_sequences
WHERE sequencename = 'assets_id_seq';

受影响表（使用 autoIncrement 主键）：

assets
asset_registry
users
stars
activity_assets
collection_assets
materials
exhibitions
galleries
以及其他所有 id BIGSERIAL PRIMARY KEY 的表

违规后果：生产环境报 duplicate key 导致用户铸造/创建失败，需紧急修复序列。

Git 提交规范

核心规则：AI 不得主动 commit

未经用户明确指示，AI 严禁执行 git commit。 只有用户在消息中明确说出"帮我 commit"、"提交吧"、"commit 一下"等类似指令时，AI 才可以执行 commit 操作。除此之外，任何情况下都不允许 AI 自行提交。

默认允许的 git 操作（只读 / 暂存）：

✅ git status、git diff、git log、git show 等只读命令
✅ git add <file> 暂存指定文件（仅在用户明确要求时）
❌ git commit —— 必须由用户明确触发
❌ git push —— 必须由用户明确触发
❌ git reset --hard、git push --force、git checkout . 等破坏性操作 —— 一律禁止

附加规范

commit 前确认：执行 commit 前，先 git status 和 git diff --staged 确认暂存区内容与用户预期一致。
commit 粒度：一个 commit 只做一件事，不要把无关修改混在一起。
默认分支保护：当前在 main / master 时，不要直接修改，先提示用户创建 feature 分支。
commit message：使用 Co-Authored-By: Claude <noreply@anthropic.com> 结尾（仅在 AI 协助生成 commit 时）。
不要自作主张：即使代码写完、测试通过、用户长时间未回复，也不要主动 commit 等待用户确认。

违规后果：污染提交历史、丢失用户未保存的修改、误推到远端等难以撤销的问题。

自审与回归检查规范

核心规则：修复后必须做整体回归检查

每次自审发现 bug 并完成修复后，必须对改动范围及周边逻辑做一次整体回归检查，防止"修复 A 引入 B"的情况。

检查流程

第一遍：定位并修复问题
- 找到自审发现的问题点
- 实施修复
第二遍：修复后整体回归（强制）
- 改动文件本身：确认修复没有破坏原有功能
- 直接调用方 / 被调用方：通过 query_graph pattern="callers_of" / callees_of" 确认上下游不受影响
- 相邻模块：同 package、同目录的相关文件需要扫一遍
- 测试用例：如果项目有测试，跑一遍相关测试
- 依赖配置：如果修改了 model/migration/route 等配置，确认下游消费方同步更新
第三遍：交叉影响检查
- 多个 bug 一起修时，要检查修复之间是否有冲突
- 公共函数 / 共享状态被多个修复点改动时，特别注意副作用

检查清单（自审模板）

修复完一个 bug 后，逐项过一遍：

修复是否解决了原始问题（不是新引入的问题）
修改的函数/方法的所有调用方是否仍能正常工作
相关单元测试是否通过 / 是否需要补充新用例
是否有条件分支（if/else、switch）只改了其中一支
错误处理 / 边界条件（空值、nil、超长、并发）是否被新逻辑覆盖
数据库 / API 字段变更是否同步更新了所有使用方
日志、错误信息、文档是否需要同步更新

违规后果

一次修复引入新 bug，调试时间翻倍
用户对代码质量失去信任
提交历史变成"反复横跳"的打补丁记录

6.9 KiB Raw Blame History Unescape Escape