Merge pull request #29593 from r-vasquez/rpk-claude-md

rpk: check in the CLAUDE.md file

Author: r-vasquez

src/go/rpk/CLAUDE.md

@@ -0,0 +1,162 @@
+# Coding Agent Onboarding Guide for `rpk`
+
+## High-Level Overview
+
+**What is rpk?**
+
+rpk is the CLI tool for Redpanda, a high-performance Apache Kafka-compatible streaming data platform. rpk is written in Go and provides commands for managing clusters, topics, groups, security, schemas, and Redpanda Cloud resources.
+
+**Repository Characteristics:**
+- **Language:** Go
+- **CLI Framework:** Cobra with modular command structure
+- **Build System:** Go modules and Bazel (dual build system)
+- **Target Platforms:** Linux (primary), macOS, Windows
+- **Key Directories:**
+  - `cmd/rpk/main.go`: Entry point, calls `cli.Execute()`
+  - `pkg/cli/`: Command modules, each major feature area has its own package
+  - `pkg/config/`: Configuration system (rpk.yaml, redpanda.yaml, profiles)
+  - `pkg/adminapi/`: Redpanda admin API client
+  - `pkg/kafka/`: Kafka protocol client (Franz-go based)
+  - `pkg/schemaregistry/`: Schema registry client
+  - `pkg/publicapi/`: Redpanda Cloud integration
+  - `pkg/out/`: Output formatting helpers (tables, structured output)
+  - `pkg/system/`, `pkg/tuners/`: System tuning and platform-specific code
+  - `pkg/plugin/`: Plugin system (managed and external plugins)
+
+## Build, Test, and Validation Instructions
+
+### Building
+```bash
+# Build the project
+./build.sh
+
+# Build via Bazel
+bazel build //:rpk
+```
+
+After running `./build.sh`, a local version of rpk will be stored under `/<OS>-<ARCH>/rpk` `/darwin-amd64/rpk` for example. Don't build in another location.
+
+### Testing
+```bash
+# Run all tests
+go test ./... -count=1
+
+# Run tests for a specific package
+go test ./pkg/cli/topic -count=1
+
+# Run a specific test
+go test ./pkg/cli/topic -run TestSpecificFunction -count=1
+```
+
+### Linting and Formatting
+```bash
+# Run linter
+make lint
+
+# Format
+make fmt
+```
+
+**Always run `make lint` after making Go code changes to catch lint issues before committing.**
+
+### Bazel Integration
+This project uses Bazel for build management with auto-generated BUILD files:
+```bash
+# Regenerate BUILD files and resolve dependencies
+make bazel
+
+# Individual bazel commands
+make bazel_generate_build  # Generate BUILD files
+make bazel_tidy           # Resolve bazel dependencies
+```
+
+**BUILD files are auto-generated by Gazelle — don't edit them manually.**
+
+---
+
+## Go-Specific Instructions
+
+### Go Coding Guidelines
+
+Check that these guidelines are followed for new code.
+
+- Use idiomatic Go patterns: avoid redundant logging, verbose string construction, and non-idiomatic output formatting.
+- Use `github.com/pkg/errors` for error wrapping. Return structured errors with context.
+- Don't start errors with a capital letter nor end with punctuation.
+- Use `afero.Fs` for filesystem operations to enable mocking.
+- Use the `require` package for assertions in tests.
+- Tests should be deterministic and not depend on external services.
+
+### Editing Rules
+
+- Before editing a file, always re-read it first to ensure you have the current content — files may have been modified externally or reverted.
+- Never remove existing variable declarations or imports unless you've verified they are truly unused in the entire file.
+- When removing or refactoring code, verify all references to changed symbols still compile before moving on.
+
+### Configuration System (`pkg/config/`)
+
+- **Multi-layered config**: Environment variables, config files, CLI flags
+- **Profile system**: Multiple named configurations for different environments
+- **Config precedence**: Flags > Environment variables > profiles > config files > defaults
+- **File locations**: `~/.config/rpk/rpk.yaml`, `./redpanda.yaml`, `/etc/redpanda/redpanda.yaml`
+- Access config via `*config.Params` passed to commands
+- Use `p.ConfigFlag`, `p.Profile`, `p.FlagOverrides` for config sources
+- Call `p.Logger()` for structured logging setup
+
+### Adding New Commands
+
+1. Create new package in `pkg/cli/` following existing patterns
+2. Implement `NewCommand(fs afero.Fs, p *config.Params) *cobra.Command`
+3. Add to root command in `pkg/cli/root.go`
+4. Run `make bazel` to regenerate BUILD files
+
+### Command Examples
+
+Many commands include the `Example` field in their cobra.Command definition to provide usage examples:
+
+```go
+Example: `
+Brief description of what the command does:
+  rpk command subcommand [flags]
+
+More specific use case:
+  rpk command subcommand --flag value
+
+Advanced usage:
+  rpk command subcommand --multiple --flags
+`,
+```
+
+**Commands with Examples:**
+- **Cluster**: `health.go`, `config/list.go`, `quotas/*.go`, `storage/*.go`
+- **Security**: `role/*.go` (assign, unassign, describe, list)
+- **Groups**: `describe.go` (includes regex examples)
+- **Container**: `start.go` (port configuration examples)
+- **Registry**: `mode/set.go`
+
+When adding examples, follow the existing pattern of showing basic usage first, then more complex scenarios with flags and options.
+
+---
+
+## rpk CLI Conventions
+
+### Output and Formatting
+- Follow existing output patterns in `pkg/out/out.go` and related helpers rather than inventing new formatting approaches.
+- For table output and ANSI coloring, use the project's custom methods rather than raw `fmt.Printf` with fixed widths.
+- Use `out.Table` for tabular data.
+- When creating a new command, use the formatter (`InstallFormatFlags`) to add support for JSON/YAML output.
+- Use `fmt.` for simpler messages.
+- Avoid mixing output methods in the same command.
+- When implementing new CLI flags, study existing similar flags in the codebase first for consistent patterns.
+
+### Logging
+- Use `zap.L().Sugar()` for structured logging.
+- In commands, use the `out` package for structured error handling and output tables.
+- Avoid using `out.MaybeDie` / `out.Die` / `os.Exit` in functions outside of command run functions.
+
+### Comments and Help Text
+- Use clear, concise comments for exported functions and types, following Go conventions.
+- Don't add redundant comments that restate the function name or state something obvious.
+- Provide detailed help text in Cobra commands for flags and usage.
+- Flag help text must NOT end in a period but should start with a capital letter.
+