sapcc-audit
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSAPCC Full-Repo Compliance Audit v2
SAPCC全仓库合规审计v2
Review every package against established review standards. Not checklist compliance — code-level review that finds over-engineering, dead code, interface violations, and inconsistent patterns.
对照既定评审标准检查每个包。这不是 checklist 式的合规检查——而是代码级评审,旨在发现过度设计、死代码、接口违规和不一致的模式。
Operator Context
操作上下文
Hardcoded Behaviors (Always Apply)
硬编码行为(始终适用)
- Review Against Project Standards: The primary question for every function is: "Would this pass review?" Not "does it follow a checklist."
- Code-Level Findings: Every finding MUST include the actual code snippet and a concrete fix showing what it should become. Abstract suggestions like "consider using X" are forbidden.
- Segment by Package: Dispatch agents by package groups, NOT by concern area. Each agent reviews its packages holistically (errors + architecture + patterns + tests together), exactly like a real PR review.
- Read the Actual Code: Agents MUST use the Read tool to read every .go file in their assigned packages. Do not guess based on file names or grep output.
- Audit Only: READS and REPORTS. Does NOT modify code unless explicitly asked with .
--fix - Skip Generic Findings: Do NOT report ,
DisallowUnknownFields, or other generic Go best practices unless they are genuinely wrong in context. Focus on sapcc-specific patterns.t.Parallel()
- 对照项目标准评审:每个函数的核心问题是:“这能通过评审吗?”而非“它是否符合checklist?”
- 代码级问题报告:每个问题必须包含实际代码片段和具体的修复示例,展示正确的写法。禁止“考虑使用X”这类抽象建议。
- 按包拆分:按包组调度Agent,而非按关注领域拆分。每个Agent会全面评审其负责的包(错误处理+架构+模式+测试),完全模拟真实的PR评审。
- 读取实际代码:Agent必须使用Read工具读取其分配包中的每个.go文件。不得根据文件名或grep结果猜测代码内容。
- 仅审计:仅读取和报告。除非明确使用参数,否则不得修改代码。
--fix - 跳过通用问题:除非在特定上下文中确实存在问题,否则不得报告、
DisallowUnknownFields或其他通用Go最佳实践。重点关注SAPCC特定模式。t.Parallel()
Default Behaviors (ON unless disabled)
默认行为(默认开启,可禁用)
- gopls MCP Integration: Agents MUST use gopls MCP tools when available — to detect workspace structure,
go_workspaceafter reading each .go file for intra-package dependency understanding,go_file_contextto verify type usage across packages (critical for export decisions),go_symbol_referencesto inspect package APIs,go_package_apito verify any fixes. This replaces grep-based analysis with type-aware analysis.go_diagnostics - Save Report: Write findings to in repo root
sapcc-audit-report.md - Before/After Code: Include "CURRENT" and "SHOULD BE" code blocks for every finding
- Directive Review Voice: Frame findings in a direct, principled review voice (references "irrelevant contrivance" or "overengineered" where applicable)
- gopls MCP集成:当可用时,Agent必须使用gopls MCP工具——用于检测工作区结构,读取每个.go文件后使用
go_workspace理解包内依赖,go_file_context用于验证跨包类型使用(对导出决策至关重要),go_symbol_references用于检查包API,go_package_api用于验证修复。这将基于grep的分析替换为类型感知分析。go_diagnostics - 保存报告:将问题报告写入仓库根目录的文件
sapcc-audit-report.md - 前后代码对比:为每个问题包含“当前代码”和“应修改为”代码块
- 指令式评审语气:以直接、基于原则的评审语气呈现问题(必要时提及“无关的冗余设计”或“过度设计”)
Optional Behaviors (OFF unless enabled)
可选行为(默认关闭,需启用)
- --fix: Auto-fix violations via code changes on a branch
- --focus [package]: Audit only one package (e.g., )
--focus internal/api - --verbose: Show passing checks too
- --fix:通过在分支上修改代码自动修复违规问题
- --focus [package]:仅审计指定包(例如:)
--focus internal/api - --verbose:同时显示通过的检查项
What the Lead Reviewer Actually Cares About (Priority Order)
首席评审官实际关注的内容(优先级排序)
These are the things that get PRs rejected, in the order the lead reviewer prioritizes them:
这些是会导致PR被拒绝的问题,按首席评审官的优先级排序:
1. Over-Engineering (Lead Reviewer's #1 Concern)
1. 过度设计(首席评审官最关注的问题)
- Interfaces with only one implementation
- Wrapper types/functions that just forward calls
- Struct types created for one-off JSON payloads
- Abstractions "for future extensibility" that add complexity now
- Config systems when env vars suffice
- 只有一个实现的接口
- 仅转发调用的包装类型/函数
- 为一次性JSON负载创建的结构体
- 为“未来扩展性”添加的抽象,却增加了当前复杂度
- 本可使用环境变量却使用配置系统
2. Dead Code
2. 死代码
- Exported functions with no callers
- Interface methods never called
- Fields set but never read
- Entire packages imported but barely used
- "TODO: remove" comments on code that should already be gone
- 无调用者的导出函数
- 从未被调用的接口方法
- 被设置但从未被读取的字段
- 被导入但几乎未使用的整个包
- 带有“TODO: remove”注释但仍未删除的代码
3. Error Message Quality (Secondary Reviewer's #1 Concern)
3. 错误消息质量(次级评审官最关注的问题)
- — useless to the caller
http.Error(w, "internal error", 500) - Error wrapping that loses the original context
- Generic messages when the actual cause is knowable
- Missing error returns (silently swallowing failures)
- ——对调用者毫无用处
http.Error(w, "internal error", 500) - 丢失原始上下文的错误包装
- 本可明确原因却使用通用消息
- 缺失错误返回(静默吞掉失败)
4. Interface Contract Violations
4. 接口契约违规
- Implementations that don't match the interface's documented behavior
- Methods that return default values instead of errors for missing items
- Inconsistent error types across implementations of the same interface
- 实现与接口文档行为不符
- 方法返回默认值而非错误以处理缺失项
- 同一接口的不同实现使用不一致的错误类型
5. Copy-Paste Structs
5. 复制粘贴的结构体
- Two structs with the same fields (one for internal, one for API response)
- Handler functions that are 90% identical (extract the common pattern)
- Duplicated validation logic
- 两个字段相同的结构体(一个用于内部,一个用于API响应)
- 90%内容相同的处理器函数(提取通用模式)
- 重复的验证逻辑
6. Pattern Consistency with Keppel
6. 与Keppel的模式一致性
- HTTP error response format (should use respondwith consistently)
- Startup pattern (osext.MustGetenv, logg.Fatal for startup errors)
- Route registration (httpapi.Compose)
- Database access patterns (gorp, easypg)
- Configuration (env vars via osext, not config files)
- HTTP错误响应格式(应始终使用respondwith)
- 启动模式(osext.MustGetenv,启动错误使用logg.Fatal)
- 路由注册(httpapi.Compose)
- 数据库访问模式(gorp, easypg)
- 配置(通过osext使用环境变量,而非配置文件)
7. Mixed Approaches
7. 混合方式
- Some handlers return JSON errors, others return text/plain
- Some constructors panic on nil args, others return errors
- Some packages use logg, others use log
- 部分处理器返回JSON错误,其他返回text/plain
- 部分构造函数在参数为nil时panic,其他返回错误
- 部分包使用logg,其他使用log
Instructions
操作步骤
Phase 1: DISCOVER
阶段1:发现
Goal: Map the repository and plan the package segmentation.
Step 1: Verify this is an sapcc project
bash
head -5 go.mod # Check module path
grep "sapcc" go.mod # Check for sapcc importsIf not an sapcc project, stop immediately.
Step 2: Map all packages
bash
find . -name "*.go" -not -path "./vendor/*" | sed 's|/[^/]*$||' | sort -uCount files per package. This determines how to segment for parallel agents.
Step 3: Plan agent segmentation
Group packages so each agent gets 5-15 files (sweet spot for thorough review).
Example for a repo with , , , , , etc.:
cmd/internal/api/internal/config/internal/storage/internal/router/| Agent | Packages | Focus |
|---|---|---|
| 1 | | Startup patterns, CLI structure |
| 2 | | HTTP handlers, error responses, routing |
| 3 | | Configuration, auth patterns |
| 4 | | Storage, persistence, error handling |
| 5 | | Core logic, concurrency |
| 6 | | Crypto, rate limiting |
| 7 | All | Testing patterns, assertions |
Adjust based on actual package sizes. Aim for 5-8 agents.
Gate: Packages mapped, agents planned. Proceed to Phase 2.
目标:映射仓库并规划包拆分。
步骤1:验证这是SAPCC项目
bash
head -5 go.mod # 检查模块路径
grep "sapcc" go.mod # 检查是否有sapcc imports如果不是SAPCC项目,立即停止。
步骤2:映射所有包
bash
find . -name "*.go" -not -path "./vendor/*" | sed 's|/[^/]*$||' | sort -u统计每个包的文件数。这将决定如何拆分以调度并行Agent。
步骤3:规划Agent拆分
将包分组,使每个Agent负责5-15个文件(这是全面评审的最佳范围)。
示例:对于包含、、、、等的仓库:
cmd/internal/api/internal/config/internal/storage/internal/router/| Agent | 包 | 重点 |
|---|---|---|
| 1 | | Startup patterns, CLI structure |
| 2 | | HTTP handlers, error responses, routing |
| 3 | | Configuration, auth patterns |
| 4 | | Storage, persistence, error handling |
| 5 | | Core logic, concurrency |
| 6 | | Crypto, rate limiting |
| 7 | All | Testing patterns, assertions |
Adjust based on actual package sizes. Aim for 5-8 agents.
检查点:已完成包映射和Agent规划。进入阶段2。
Phase 2: DISPATCH
阶段2:调度
Goal: Launch parallel agents that review packages against project standards.
Each agent gets this prompt:
You are reviewing code in an SAP Converged Cloud Go project against established
review standards. Your job is to find things that would actually be commented on
or rejected in a PR.
PACKAGES TO REVIEW: [list of packages with full paths]
Read EVERY .go file in these packages using the Read tool. For each file:
1. **Over-engineering**: Is there an abstraction that isn't justified?
- Interface with one implementation? → "Just use the concrete type." Project convention: only create interfaces when there are 2+ real implementations.
- Wrapper function that adds nothing? → "Delete this, call the real function"
- Struct for one-time JSON? → "Use fmt.Sprintf + json.Marshal" (per project convention)
- Option struct for constructor? → "Just use positional params." Project convention uses 7-8 positional params, never option structs.
- Config file/viper? → "Use osext.MustGetenv." Project convention never uses config files. Pure env vars only.
2. **Dead code**: Are there exported functions with no callers outside the package?
Use Grep to check for callers: `grep -r "FunctionName" --include="*.go"`
If no callers exist, flag it.
3. **Error messages**: Read every fmt.Errorf and http.Error call.
- Does the message tell you WHAT failed and WHERE?
- Error wrapping: uses %w when caller needs errors.Is/As, %s with .Error() to intentionally break chain
- Message format: "cannot <operation>: %w" or "while <operation>: %w" with relevant identifiers
- Would a user/operator reading this know what to do?
- "internal error" with no context = CRITICAL
- Never log AND return the same error. Primary error returned, secondary/cleanup errors logged.
4. **Constructor patterns**:
- Constructor should be `NewX(deps...) *X` — never returns error (construction is infallible)
- Uses positional struct literal init: `&API{cfg, ad, fd, sd, ...}` (no field names)
- Injects default functions for test doubles: `time.Now`, etc.
- Override pattern for test doubles: fluent `OverrideTimeNow(fn) *T` methods
5. **Interface contracts**: If the package implements an interface from another package:
- Read the interface definition
- Check if the implementation actually satisfies the contract
- Does it return correct error types? Default values where errors are expected?
- Interfaces should be defined in the consumer package, not the implementation package
6. **Copy-paste**: Are there two structs, functions, or code blocks that are >70% similar?
7. **HTTP handler patterns**: Does this code match keppel patterns?
- Handlers: methods on *API with `handleVerbResource(w, r)` signature
- Auth: called inline at top of handler, NOT middleware
- JSON decode: `json.NewDecoder` + `DisallowUnknownFields()`
- Responses: `respondwith.JSON(w, status, map[string]any{"key": val})`
- Internal errors: `respondwith.ObfuscatedErrorText(w, err)` — hides 500s from clients
- Route registration: one `AddTo(*mux.Router)` per API domain, composed via `httpapi.Compose`
8. **Database patterns**:
- SQL queries as package-level `var` with `sqlext.SimplifyWhitespace()`
- PostgreSQL `$1, $2` params (never `?`)
- gorp for simple CRUD, raw SQL for complex queries
- Transactions: `db.Begin()` + `defer sqlext.RollbackUnlessCommitted(tx)`
- NULL: `Option[T]` (from majewsky/gg/option), not `*T` pointers
9. **Type patterns**:
- Named string types for domain concepts: `type AccountName string`
- String enums with typed constants (NOT iota): `const CleanSeverity VulnerabilityStatus = "Clean"`
- Model types use `db:"column"` tags; API types use `json:"field"` tags — separate types
- Pointer receivers for all struct methods (value receivers only for tiny data-only types)
10. **Logging patterns**:
- `logg.Fatal` ONLY in cmd/ packages for startup failures
- `logg.Error` for secondary/cleanup errors (never for primary errors)
- `logg.Info` for operational events
- Never log.Printf or fmt.Printf for logging
- Panics only for impossible states, annotated with "why was this not caught by Validate!?"
For EACH finding, output:目标:启动并行Agent,对照项目标准评审包。
每个Agent将收到以下提示:
You are reviewing code in an SAP Converged Cloud Go project against established
review standards. Your job is to find things that would actually be commented on
or rejected in a PR.
PACKAGES TO REVIEW: [list of packages with full paths]
Read EVERY .go file in these packages using the Read tool. For each file:
1. **Over-engineering**: Is there an abstraction that isn't justified?
- Interface with one implementation? → "Just use the concrete type." Project convention: only create interfaces when there are 2+ real implementations.
- Wrapper function that adds nothing? → "Delete this, call the real function"
- Struct for one-time JSON? → "Use fmt.Sprintf + json.Marshal" (per project convention)
- Option struct for constructor? → "Just use positional params." Project convention uses 7-8 positional params, never option structs.
- Config file/viper? → "Use osext.MustGetenv." Project convention never uses config files. Pure env vars only.
2. **Dead code**: Are there exported functions with no callers outside the package?
Use Grep to check for callers: `grep -r "FunctionName" --include="*.go"`
If no callers exist, flag it.
3. **Error messages**: Read every fmt.Errorf and http.Error call.
- Does the message tell you WHAT failed and WHERE?
- Error wrapping: uses %w when caller needs errors.Is/As, %s with .Error() to intentionally break chain
- Message format: "cannot <operation>: %w" or "while <operation>: %w" with relevant identifiers
- Would a user/operator reading this know what to do?
- "internal error" with no context = CRITICAL
- Never log AND return the same error. Primary error returned, secondary/cleanup errors logged.
4. **Constructor patterns**:
- Constructor should be `NewX(deps...) *X` — never returns error (construction is infallible)
- Uses positional struct literal init: `&API{cfg, ad, fd, sd, ...}` (no field names)
- Injects default functions for test doubles: `time.Now`, etc.
- Override pattern for test doubles: fluent `OverrideTimeNow(fn) *T` methods
5. **Interface contracts**: If the package implements an interface from another package:
- Read the interface definition
- Check if the implementation actually satisfies the contract
- Does it return correct error types? Default values where errors are expected?
- Interfaces should be defined in the consumer package, not the implementation package
6. **Copy-paste**: Are there two structs, functions, or code blocks that are >70% similar?
7. **HTTP handler patterns**: Does this code match keppel patterns?
- Handlers: methods on *API with `handleVerbResource(w, r)` signature
- Auth: called inline at top of handler, NOT middleware
- JSON decode: `json.NewDecoder` + `DisallowUnknownFields()`
- Responses: `respondwith.JSON(w, status, map[string]any{"key": val})`
- Internal errors: `respondwith.ObfuscatedErrorText(w, err)` — hides 500s from clients
- Route registration: one `AddTo(*mux.Router)` per API domain, composed via `httpapi.Compose`
8. **Database patterns**:
- SQL queries as package-level `var` with `sqlext.SimplifyWhitespace()`
- PostgreSQL `$1, $2` params (never `?`)
- gorp for simple CRUD, raw SQL for complex queries
- Transactions: `db.Begin()` + `defer sqlext.RollbackUnlessCommitted(tx)`
- NULL: `Option[T]` (from majewsky/gg/option), not `*T` pointers
9. **Type patterns**:
- Named string types for domain concepts: `type AccountName string`
- String enums with typed constants (NOT iota): `const CleanSeverity VulnerabilityStatus = "Clean"`
- Model types use `db:"column"` tags; API types use `json:"field"` tags — separate types
- Pointer receivers for all struct methods (value receivers only for tiny data-only types)
10. **Logging patterns**:
- `logg.Fatal` ONLY in cmd/ packages for startup failures
- `logg.Error` for secondary/cleanup errors (never for primary errors)
- `logg.Info` for operational events
- Never log.Printf or fmt.Printf for logging
- Panics only for impossible states, annotated with "why was this not caught by Validate!?"
For EACH finding, output:[MUST-FIX / SHOULD-FIX / NIT]: [One-line summary]
[MUST-FIX / SHOULD-FIX / NIT]: [One-line summary]
File:
Convention: "[What a lead reviewer would actually write in a PR comment]"
path/to/file.go:LINECurrent code:
go
[actual code from the file, 3-10 lines]Should be:
go
[what the code should look like after fixing]Why: [One sentence explaining the principle]
SEVERITY GUIDE:
- MUST-FIX: Would block the PR (data loss, interface violation, wrong behavior)
- SHOULD-FIX: Would get a strong review comment (dead code, copy-paste, bad errors)
- NIT: Would get a comment but not block (style, naming, minor simplification)
DO NOT report:
- Generic Go best practices (t.Parallel, DisallowUnknownFields, context.Context first)
- Things that are actually fine but could theoretically be "better"
- Suggestions that add complexity without clear benefit
DO report:
- Real over-engineering (lead reviewer's #1 concern)
- Actually useless error messages (secondary reviewer's #1 concern)
- Dead code that should be deleted
- Interface contract bugs
- Constructor/config patterns that don't match keppel
- Inconsistent patterns within the same repo
**Dispatch all agents in a single message using the Task tool with subagent_type=golang-general-engineer.**
**Gate**: All agents dispatched. Proceed to Phase 3.File:
Convention: "[What a lead reviewer would actually write in a PR comment]"
path/to/file.go:LINECurrent code:
go
[actual code from the file, 3-10 lines]Should be:
go
[what the code should look like after fixing]Why: [One sentence explaining the principle]
SEVERITY GUIDE:
- MUST-FIX: Would block the PR (data loss, interface violation, wrong behavior)
- SHOULD-FIX: Would get a strong review comment (dead code, copy-paste, bad errors)
- NIT: Would get a comment but not block (style, naming, minor simplification)
DO NOT report:
- Generic Go best practices (t.Parallel, DisallowUnknownFields, context.Context first)
- Things that are actually fine but could theoretically be "better"
- Suggestions that add complexity without clear benefit
DO report:
- Real over-engineering (lead reviewer's #1 concern) n- Actually useless error messages (secondary reviewer's #1 concern)
- Dead code that should be deleted
- Interface contract bugs
- Constructor/config patterns that don't match keppel
- Inconsistent patterns within the same repo
**使用Task工具在单个消息中调度所有Agent,指定subagent_type=golang-general-engineer。**
**检查点**:所有Agent已调度。进入阶段3。Phase 3: COMPILE REPORT
阶段3:编译报告
Goal: Aggregate findings into a code-level compliance report.
Step 1: Collect and deduplicate
Some findings may overlap (e.g., dead code agent and architecture agent flag the same unused function). Deduplicate by file:line.
Step 2: Write the report
Create :
sapcc-audit-report.mdmarkdown
undefined目标:将问题汇总为代码级合规报告。
步骤1:收集并去重
部分问题可能重叠(例如:死代码Agent和架构Agent标记同一个未使用的函数)。按文件:行去重。
步骤2:编写报告
创建:
sapcc-audit-report.mdmarkdown
undefinedSAPCC Code Review: [repo name]
SAPCC Code Review: [repo name]
Reviewed by: Lead & secondary reviewer standards (simulated)
Date: [date]
Packages: [N] packages, [M] Go files
Reviewed by: Lead & secondary reviewer standards (simulated)
Date: [date]
Packages: [N] packages, [M] Go files
Verdict
Verdict
[One paragraph: Would this pass review? What's the overall impression?]
[One paragraph: Would this pass review? What's the overall impression?]
Must-Fix (Would Block PR)
Must-Fix (Would Block PR)
[Each finding with current/should-be code]
[Each finding with current/should-be code]
Should-Fix (Strong Review Comments)
Should-Fix (Strong Review Comments)
[Each finding with current/should-be code]
[Each finding with current/should-be code]
Nits
Nits
[Each finding, brief]
[Each finding, brief]
What's Done Well
What's Done Well
[Genuine positives — things a reviewer would note approvingly]
[Genuine positives — things a reviewer would note approvingly]
Package-by-Package Summary
Package-by-Package Summary
| Package | Files | Must-Fix | Should-Fix | Nit | Verdict |
|---|---|---|---|---|---|
| internal/api | N | X | Y | Z | [emoji] |
| ... |
**Step 3: Display summary**
Show the verdict, must-fix count, and top 5 findings inline. Point to the full report file.
**Gate**: Report complete.
---| Package | Files | Must-Fix | Should-Fix | Nit | Verdict |
|---|---|---|---|---|---|
| internal/api | N | X | Y | Z | [emoji] |
| ... |
**步骤3:显示摘要**
Show the verdict, must-fix count, and top 5 findings inline. Point to the full report file.
**检查点**:Report complete.
---Anti-Patterns
反模式
AP-1: Checklist Compliance Instead of Code Review
AP-1: Checklist Compliance Instead of Code Review
What it looks like: "Error handling: 7 warnings" without showing actual code
Why wrong: A real reviewer doesn't review with checklists. They read code and react.
Do instead: Show the actual problematic code and what it should become.
What it looks like: "Error handling: 7 warnings" without showing actual code
Why wrong: A real reviewer doesn't review with checklists. They read code and react.
Do instead: Show the actual problematic code and what it should become.
AP-2: Generic Go Suggestions
AP-2: Generic Go Suggestions
What it looks like: "Consider using t.Parallel()" / "Add DisallowUnknownFields()"
Why wrong: These are generic best practices, not sapcc-specific patterns. They don't reflect what the project's reviewers actually care about.
Do instead: Focus on over-engineering, dead code, error quality, interface violations — the things that actually get PRs rejected.
What it looks like: "Consider using t.Parallel()" / "Add DisallowUnknownFields()"
Why wrong: These are generic best practices, not sapcc-specific patterns. They don't reflect what the project's reviewers actually care about.
Do instead: Focus on over-engineering, dead code, error quality, interface violations — the things that actually get PRs rejected.
AP-3: Segment by Concern Instead of Package
AP-3: Segment by Concern Instead of Package
What it looks like: "Error Handling Agent" checks all files for error patterns only
Why wrong: Real code review reads a file holistically. An error handling issue might actually be an architecture issue. Segmenting by concern produces shallow findings.
Do instead: Segment by package. Each agent reads all files in its packages and reviews everything.
What it looks like: "Error Handling Agent" checks all files for error patterns only
Why wrong: Real code review reads a file holistically. An error handling issue might actually be an architecture issue. Segmenting by concern produces shallow findings.
Do instead: Segment by package. Each agent reads all files in its packages and reviews everything.
AP-4: Suggesting Complexity Additions
AP-4: Suggesting Complexity Additions
What it looks like: "Add response envelopes" / "Create a config validation layer"
Why wrong: The project's strongest convention is AGAINST adding complexity. If something works simply, don't make it complex.
Do instead: Frame suggestions as simplifications. "Remove this abstraction" > "Add this abstraction."
What it looks like: "Add response envelopes" / "Create a config validation layer"
Why wrong: The project's strongest convention is AGAINST adding complexity. If something works simply, don't make it complex.
Do instead: Frame suggestions as simplifications. "Remove this abstraction" > "Add this abstraction."
Calibration Examples
校准示例
Good Finding (Would Appear in a Project Review)
Good Finding (Would Appear in a Project Review)
undefinedundefinedSHOULD-FIX: configResponse is a maintenance-hazard copy of DestConfig
SHOULD-FIX: configResponse is a maintenance-hazard copy of DestConfig
File:
Convention: "This is just DestConfig with JSON tags. Add the tags to DestConfig and delete this."
internal/api/config_handler.go:42Current code:
type configResponse struct {
TenantID string
BucketName string
Region string
}
json:"tenant_id"json:"bucket_name"json:"region"Should be:
// Add JSON tags to the existing DestConfig type
type DestConfig struct {
TenantID string
BucketName string
Region string
}
json:"tenant_id"json:"bucket_name"json:"region"Why: Duplicate structs drift apart over time. One source of truth.
undefinedFile:
Convention: "This is just DestConfig with JSON tags. Add the tags to DestConfig and delete this."
internal/api/config_handler.go:42Current code:
type configResponse struct {
TenantID string
BucketName string
Region string
}
json:"tenant_id"json:"bucket_name"json:"region"Should be:
// Add JSON tags to the existing DestConfig type
type DestConfig struct {
TenantID string
BucketName string
Region string
}
json:"tenant_id"json:"bucket_name"json:"region"Why: Duplicate structs drift apart over time. One source of truth.
undefinedBad Finding (Would NOT Appear in a Project Review)
Bad Finding (Would NOT Appear in a Project Review)
undefinedundefinedWARNING: Consider adding DisallowUnknownFields
WARNING: Consider adding DisallowUnknownFields
File:
This JSON decoder could benefit from DisallowUnknownFields() to catch typos.
internal/config/loader.go:15This is too generic. A project reviewer wouldn't comment on this in most cases.
---File:
This JSON decoder could benefit from DisallowUnknownFields() to catch typos.
internal/config/loader.go:15This is too generic. A project reviewer wouldn't comment on this in most cases.
---Reference Loading Strategy
Reference Loading Strategy
The essential review rules are already inline in Section "What the Lead Reviewer Actually Cares About" above and in each agent's dispatch prompt. Reference files provide supplementary depth when an agent needs it.
Reference files live at (or globally).
skills/go-sapcc-conventions/references/~/.claude/skills/go-sapcc-conventions/references/Per-agent reference loading (included in each agent's dispatch prompt based on assigned packages):
| Package Type | Reference to Load |
|---|---|
HTTP handlers ( | |
Test files ( | |
| Error handling heavy packages | |
| Architecture/drivers | |
| Build/CI config | |
| Import-heavy files | |
Always available for calibration (load only when needed):
- — Quick-check findings against known anti-patterns
anti-patterns.md - — Calibrate review tone and severity
review-standards-lead.md
Anti-pattern: Do NOT tell every agent to read the full sapcc-code-patterns.md. The rules are already inline. Load reference files only for domain-specific depth.
The essential review rules are already inline in Section "What the Lead Reviewer Actually Cares About" above and in each agent's dispatch prompt. Reference files provide supplementary depth when an agent needs it.
Reference files live at (or globally).
skills/go-sapcc-conventions/references/~/.claude/skills/go-sapcc-conventions/references/Per-agent reference loading (included in each agent's dispatch prompt based on assigned packages):
| Package Type | Reference to Load |
|---|---|
HTTP handlers ( | |
Test files ( | |
| Error handling heavy packages | |
| Architecture/drivers | |
| Build/CI config | |
| Import-heavy files | |
Always available for calibration (load only when needed):
- — Quick-check findings against known anti-patterns
anti-patterns.md - — Calibrate review tone and severity
review-standards-lead.md
Anti-pattern: Do NOT tell every agent to read the full sapcc-code-patterns.md. The rules are already inline. Load reference files only for domain-specific depth.
Integration
Integration
- Router: routes via "sapcc audit", "sapcc compliance", "sapcc lead review"
/do - Pairs with: (the rules),
go-sapcc-conventions(the executor)golang-general-engineer - Prerequisite: must be loaded so agents have the rules
go-sapcc-conventions
- Router: routes via "sapcc audit", "sapcc compliance", "sapcc lead review"
/do - Pairs with: (the rules),
go-sapcc-conventions(the executor)golang-general-engineer - Prerequisite: must be loaded so agents have the rules
go-sapcc-conventions