pkg/ Directory Guidelines

Guidelines for AI agents working on packages in the pkg/ directory.

Overview

The pkg/ directory contains public packages that can be imported by external code. These packages provide shared utilities, configuration management, logging, and common functionality.

Directory Structure

pkg/
├── config/         # Configuration management (account, wallet, loader)
├── cryptocurrency/ # Crypto utilities (btc, bch, eth, xrp)
├── db/             # Database connections (mysql, sqlite)
├── debug/          # Debug utilities
├── decimal/        # Decimal number utilities
├── di/             # Legacy DI container (panic allowed)
├── grpc/           # gRPC client utilities
├── logger/         # Logging (global, slog, noop)
├── null/           # Null value converters
├── retry/          # Retry with exponential backoff
├── serializer/     # Serialization utilities
├── uuid/           # UUID generation
└── websocket/      # WebSocket client

Critical Rule

Packages in pkg/ MUST NOT import from internal/ directory.

This is non-negotiable:

• pkg/ = public APIs for external code
• internal/ = internal implementation details
• Mixing breaks encapsulation and creates circular dependencies

Common Commands

make go-lint      # Lint and auto-fix
make check-build  # Build verification
make go-test       # Run unit tests
make tidy         # go mod tidy

Patterns

Avoid

• Importing from internal/
• Using panic (except pkg/di legacy)
• Commented-out code
• Ignoring errors
• Logging sensitive information

Recommended

• Self-contained utility functions
• Proper error wrapping with context
• Use context.Context for cancellation
• Unit tests for exported functions

Important Notes

• Financial project - make changes carefully
• Public APIs - consider backward compatibility
• DO NOT edit files with DO NOT EDIT comments

References

Rules

• .claude/rules/go/conventions.md - Go conventions

Guidelines

• Coding Conventions
• Security
• Testing

Other

• AGENTS.md - Root agent guidelines
• internal/AGENTS.md - Internal packages