Go

# Go Development Instructions

Follow idiomatic Go practices and community standards when writing Go code. These instructions are based on [Effective Go](https://go.dev/doc/effective_go), [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments), and [Google's Go Style Guide](https://google.github.io/styleguide/go/).

General Instructions

- Write simple, clear, and idiomatic Go code

- Favor clarity and simplicity over cleverness

- Follow the principle of least surprise

- Keep the happy path left-aligned (minimize indentation)

- Return early to reduce nesting

- Prefer early return over if-else chains; use `if condition { return }` pattern to avoid else blocks

- Make the zero value useful

- Write self-documenting code with clear, descriptive names

- Document exported types, functions, methods, and packages

- Use Go modules for dependency management

- Leverage the Go standard library instead of reinventing the wheel (e.g., use `strings.Builder` for string concatenation, `filepath.Join` for path construction)

- Prefer standard library solutions over custom implementations when functionality exists

- Write comments in English by default; translate only upon user request

- Avoid using emoji in code and comments

Naming Conventions

Packages

- Use lowercase, single-word package names

- Avoid underscores, hyphens, or mixedCaps

- Choose names that describe what the package provides, not what it contains

- Avoid generic names like `util`, `common`, or `base`

- Package names should be singular, not plural

#### Package Declaration Rules (CRITICAL):

- **NEVER duplicate `package` declarations** - each Go file must have exactly ONE `package` line

- When editing an existing `.go` file:

- **PRESERVE** the existing `package` declaration - do not add another one

- If you need to replace the entire file content, start with the existing package name

- When creating a new `.go` file:

- **BEFORE writing any code**, check what package name other `.go` files in the same directory use

- Use the SAME package name as existing files in that directory

- If it's a new directory, use the directory name as the package name

- Write **exactly one** `package <name>` line at the very top of the file

- When using file creation or replacement tools:

- **ALWAYS verify** the target file doesn't already have a `package` declaration before adding one

- If replacing file content, include only ONE `package` declaration in the new content

- **NEVER** create files with multiple `package` lines or duplicate declarations

Variables and Functions

- Use mixedCaps or MixedCaps (camelCase) rather than underscores

- Keep names short but descriptive

- Use single-letter variables only for very short scopes (like loop indices)

- Exported names start with a capital letter

- Unexported names start with a lowercase letter

- Avoid stuttering (e.g., avoid `http.HTTPServer`, prefer `http.Server`)

Interfaces

- Name interfaces with -er suffix when possible (e.g., `Reader`, `Writer`, `Formatter`)

- Single-method interfaces should be named after the method (e.g., `Read` → `Reader`)

- Keep interfaces small and focused

Constants

- Use MixedCaps for exported constants

- Use mixedCaps for unexported constants

- Group related constants using `const` blocks

- Consider using typed constants for better type safety

Code Style and Formatting

Formatting

- Always use `gofmt` to format code

- Use `goimports` to manage imports automatically

- Keep line length reasonable (no hard limit, but consider readability)

- Add blank lines to separate logical groups of code

Comments

- Strive for self-documenting code; prefer clear variable names, function names, and code structure over comments

- Write comments only when necessary to explain complex logic, business rules, or non-obvious behavior

- Write comments in complete sentences in English by default

- Translate comments to other languages only upon specific user request

- Start sentences wi