22
33This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
44
5+ ## Architecture Overview
6+ ### Core Components
7+ 1 . ** Backend code** (` engine/ ` )
8+ 1.1. ** Entry Points** (` cmd/ ` )
9+ 2 . ** Frontend code** (` ui/ ` )
10+
511## Build/Test/Lint Commands
612- Build all components: ` cd engine && make build `
713- Lint code: ` cd engine && make lint `
@@ -20,4 +26,123 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
2026- Follow standard Go import ordering
2127- Group similar functions together
2228- Error messages should be descriptive and actionable
23- - UI uses pnpm for package management
29+ - UI uses pnpm for package management
30+
31+ ## Important Backend Workflow Notes
32+
33+ - Always run tests, linter and normalize comments BEFORE committing anything
34+ - Run formatting, code generation, linting and testing on completion
35+ - Never commit without running completion sequence
36+ - Run tests and linter after making significant changes to verify functionality
37+ - IMPORTANT: Never put into commit message any mention of Claude or Claude Code
38+ - IMPORTANT: Never include "Test plan" sections in PR descriptions
39+ - Do not add comments that describe changes, progress, or historical modifications
40+ - Comments should only describe the current state and purpose of the code, not its history or evolution
41+ - After important functionality added, update README.md accordingly
42+ - When merging master changes to an active branch, make sure both branches are pulled and up to date first
43+ - Don't leave commented out code in place
44+ - Avoid multi-level nesting
45+ - Avoid multi-level ifs, never use else if
46+ - Never use goto
47+ - Avoid else branches if possible
48+ - Write tests in compact form by fitting struct fields to a single line (up to 130 characters)
49+ - Before any significant refactoring, ensure all tests pass and consider creating a new branch
50+ - When refactoring, editing, or fixing failed tests:
51+ - Do not redesign fundamental parts of the code architecture
52+ - If unable to fix an issue with the current approach, report the problem and ask for guidance
53+ - Focus on minimal changes to address the specific issue at hand
54+ - Preserve the existing patterns and conventions of the codebase
55+
56+ ## Backend Code Style Guidelines
57+
58+ ### Import Organization
59+ - Organize imports in the following order:
60+ 1 . Standard library packages first (e.g., "fmt", "context")
61+ 2 . A blank line separator
62+ 3 . Third-party packages
63+ 4 . A blank line separator
64+ 5 . Project imports (e.g., "gitlab.com/postgres-ai/database-lab/v3/pkg/* ")
65+ - Example:
66+ ``` go
67+ import (
68+ " context"
69+ " fmt"
70+ " net/http"
71+
72+ " github.com/docker/docker/api/types"
73+ " github.com/gorilla/mux"
74+
75+ " gitlab.com/postgres-ai/database-lab/v3/pkg/util/branching"
76+ )
77+ ```
78+
79+ ### Error Handling
80+ - Return errors to the caller rather than using panics
81+ - Use descriptive error messages that help with debugging
82+ - Use error wrapping: ` fmt.Errorf("failed to process request: %w", err) `
83+ - Check errors immediately after function calls
84+ - Return early when possible to avoid deep nesting
85+
86+ ### Variable Naming
87+ - Use descriptive camelCase names for variables and functions
88+ - Good: ` notFoundHandler ` , ` requestContext ` , ` userID `
89+ - Bad: ` not_found_handler ` , ` x ` , ` temp1 `
90+ - Be consistent with abbreviations (e.g., ` httpClient ` not ` HTTPClient ` )
91+ - Local scope variables can be short (e.g., "lmt" instead of "orderLimit")
92+ - Use constants for magic numbers and strings
93+ - Use meaningful names for constants and enums
94+
95+ ### Function Parameters
96+ - Group related parameters together logically
97+ - Use descriptive parameter names that indicate their purpose
98+ - Consider using parameter structs for functions with many (4+) parameters
99+ - If function returns 3 or more results, consider wrapping in Result/Response struct
100+ - If function accepts 3 or more input parameters, consider wrapping in Request/Input struct (but never add context to struct)
101+
102+ ### Documentation
103+ - All exported functions, types, and methods must have clear godoc comments
104+ - Begin comments with the name of the element being documented
105+ - Include usage examples for complex functions
106+ - Document any non-obvious behavior or edge cases
107+ - All comments should be lowercase, except for godoc public functions and methods
108+ - IMPORTANT: all comments except godoc comments must be lowercase, test messages must be lowercase, log messages must be lowercase
109+
110+ ### Code Structure
111+ - Keep code modular with focused responsibilities
112+ - Limit file sizes to 300-500 lines when possible
113+ - Group related functionality in the same package
114+ - Use interfaces to define behavior and enable mocking for tests
115+ - Keep code minimal and avoid unnecessary complexity
116+ - Don't keep old functions for imaginary compatibility
117+ - Interfaces should be defined on the consumer side (idiomatic Go)
118+ - Aim to pass interfaces but return concrete types when possible
119+ - Consider nested functions when they simplify complex functions
120+
121+ ### Code Layout
122+ - Keep cyclomatic complexity under 30
123+ - Function size preferences:
124+ - Aim for functions around 50-60 lines when possible
125+ - Don't break down functions too small as it can reduce readability
126+ - Maintain focus on a single responsibility per function
127+ - Keep lines under 130 characters when possible
128+ - Avoid if-else chains and nested conditionals:
129+ - Never use long if-else-if chains; use switch statements instead
130+ - Prefer early returns to reduce nesting depth
131+ - Extract complex conditions into separate boolean functions or variables
132+ - Use context structs or functional options instead of multiple boolean flags
133+
134+ ### Testing
135+ - Write thorough tests with descriptive names (e.g., ` TestRouter_HandlesMiddlewareCorrectly ` )
136+ - Prefer subtests or table-based tests, using Testify
137+ - Use table-driven tests for testing multiple cases with the same logic
138+ - Test both success and error scenarios
139+ - Mock external dependencies to ensure unit tests are isolated and fast
140+ - Aim for at least 80% code coverage
141+ - Keep tests compact but readable
142+ - If test has too many subtests, consider splitting it to multiple tests
143+ - Never disable tests without a good reason and approval
144+ - Important: Never update code with special conditions to just pass tests
145+ - Don't create new test files if one already exists matching the source file name
146+ - Add new tests to existing test files following the same naming and structuring conventions
147+ - Don't add comments before subtests, t.Run("description") already communicates what test case is doing
148+ - Never use godoc-style comments for test functions
0 commit comments