AGENTS.md

1# `pkg/` Directory Guidelines
2 
3Guidelines for AI agents working on packages in the `pkg/` directory.
4 
5## Overview
6 
7The `pkg/` directory contains **public packages** that can be imported by external code.
8These packages provide shared utilities, configuration management, logging, and common functionality.
9 
10## Directory Structure
11 
12```
13pkg/
14├── config/         # Configuration management (account, wallet, loader)
15├── cryptocurrency/ # Crypto utilities (btc, bch, eth, xrp)
16├── db/             # Database connections (mysql, sqlite)
17├── debug/          # Debug utilities
18├── decimal/        # Decimal number utilities
19├── di/             # Legacy DI container (panic allowed)
20├── grpc/           # gRPC client utilities
21├── logger/         # Logging (global, slog, noop)
22├── null/           # Null value converters
23├── retry/          # Retry with exponential backoff
24├── serializer/     # Serialization utilities
25├── uuid/           # UUID generation
26└── websocket/      # WebSocket client
27```
28 
29## Critical Rule
30 
31**Packages in `pkg/` MUST NOT import from `internal/` directory.**
32 
33This is non-negotiable:
34 
35- `pkg/` = public APIs for external code
36- `internal/` = internal implementation details
37- Mixing breaks encapsulation and creates circular dependencies
38 
39## Common Commands
40 
41```bash
42make go-lint      # Lint and auto-fix
43make check-build  # Build verification
44make go-test       # Run unit tests
45make tidy         # go mod tidy
46```
47 
48## Patterns
49 
50### Avoid
51 
52- Importing from `internal/`
53- Using `panic` (except `pkg/di` legacy)
54- Commented-out code
55- Ignoring errors
56- Logging sensitive information
57 
58### Recommended
59 
60- Self-contained utility functions
61- Proper error wrapping with context
62- Use `context.Context` for cancellation
63- Unit tests for exported functions
64 
65## Important Notes
66 
67- Financial project - make changes carefully
68- Public APIs - consider backward compatibility
69- **DO NOT** edit files with `DO NOT EDIT` comments
70 
71## References
72 
73### Rules
74 
75- `.claude/rules/go/conventions.md` - Go conventions
76 
77### Guidelines
78 
79- [Coding Conventions](../docs/guidelines/coding-conventions.md)
80- [Security](../docs/guidelines/security.md)
81- [Testing](../docs/guidelines/testing.md)
82 
83### Other
84 
85- [AGENTS.md](../AGENTS.md) - Root agent guidelines
86- [internal/AGENTS.md](../internal/AGENTS.md) - Internal packages
87