166 lines
6.9 KiB
Markdown
166 lines
6.9 KiB
Markdown
<!-- code-review-graph MCP tools -->
|
||
## 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
|
||
|
||
1. The graph auto-updates on file changes (via hooks).
|
||
2. Use `detect_changes` for code review.
|
||
3. Use `get_affected_flows` to understand impact.
|
||
4. 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 手动补数据
|
||
|
||
**规范要求**：
|
||
|
||
1. **任何手动指定 ID 的 INSERT 语句，末尾必须同步重置序列**：
|
||
```sql
|
||
-- 错误示例（会导致序列不同步）
|
||
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));
|
||
```
|
||
|
||
2. **脚本文件规范**：所有输出 SQL 的 Go 脚本（如 `backend/scripts/*.go`），必须在生成的 SQL 末尾包含序列重置语句：
|
||
```go
|
||
fmt.Printf(`SELECT setval('%s_id_seq', (SELECT MAX(id) FROM %s));\n`, tableName, tableName)
|
||
```
|
||
|
||
3. **新表创建时**：预留足够的序列起始值给测试数据：
|
||
```sql
|
||
CREATE SEQUENCE assets_id_seq START WITH 10000;
|
||
```
|
||
|
||
4. **定期检查**：环境部署后执行以下 SQL 确认序列健康：
|
||
```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 .` 等破坏性操作 —— 一律禁止
|
||
|
||
### 附加规范
|
||
|
||
1. **commit 前确认**：执行 commit 前，先 `git status` 和 `git diff --staged` 确认暂存区内容与用户预期一致。
|
||
2. **commit 粒度**：一个 commit 只做一件事，不要把无关修改混在一起。
|
||
3. **默认分支保护**：当前在 `main` / `master` 时，不要直接修改，先提示用户创建 feature 分支。
|
||
4. **commit message**：使用 `Co-Authored-By: Claude <noreply@anthropic.com>` 结尾（仅在 AI 协助生成 commit 时）。
|
||
5. **不要自作主张**：即使代码写完、测试通过、用户长时间未回复，也**不要**主动 commit 等待用户确认。
|
||
|
||
**违规后果**：污染提交历史、丢失用户未保存的修改、误推到远端等难以撤销的问题。
|
||
|
||
---
|
||
|
||
## 自审与回归检查规范
|
||
|
||
### 核心规则：修复后必须做整体回归检查
|
||
|
||
**每次自审发现 bug 并完成修复后，必须对改动范围及周边逻辑做一次整体回归检查**，防止"修复 A 引入 B"的情况。
|
||
|
||
### 检查流程
|
||
|
||
1. **第一遍：定位并修复问题**
|
||
- 找到自审发现的问题点
|
||
- 实施修复
|
||
|
||
2. **第二遍：修复后整体回归（强制）**
|
||
- **改动文件本身**：确认修复没有破坏原有功能
|
||
- **直接调用方 / 被调用方**：通过 `query_graph pattern="callers_of"` / `callees_of"` 确认上下游不受影响
|
||
- **相邻模块**：同 package、同目录的相关文件需要扫一遍
|
||
- **测试用例**：如果项目有测试，跑一遍相关测试
|
||
- **依赖配置**：如果修改了 model/migration/route 等配置，确认下游消费方同步更新
|
||
|
||
3. **第三遍：交叉影响检查**
|
||
- 多个 bug 一起修时，要检查**修复之间**是否有冲突
|
||
- 公共函数 / 共享状态被多个修复点改动时，特别注意副作用
|
||
|
||
### 检查清单（自审模板）
|
||
|
||
修复完一个 bug 后，逐项过一遍：
|
||
|
||
- [ ] 修复是否解决了**原始问题**（不是新引入的问题）
|
||
- [ ] 修改的函数/方法的**所有调用方**是否仍能正常工作
|
||
- [ ] 相关单元测试是否通过 / 是否需要补充新用例
|
||
- [ ] 是否有**条件分支**（if/else、switch）只改了其中一支
|
||
- [ ] 错误处理 / 边界条件（空值、nil、超长、并发）是否被新逻辑覆盖
|
||
- [ ] 数据库 / API 字段变更是否同步更新了所有使用方
|
||
- [ ] 日志、错误信息、文档是否需要同步更新
|
||
|
||
### 违规后果
|
||
|
||
- 一次修复引入新 bug，调试时间翻倍
|
||
- 用户对代码质量失去信任
|
||
- 提交历史变成"反复横跳"的打补丁记录
|