AGENTS.md

1<!--
2⚠️ AUTO-GENERATED FILE — DO NOT EDIT
3Source: template/pages/AGENTS.tpl.md · Run `make docs` to regenerate.
4-->
5 
6# Agent Guidelines for go-crypto-wallet
7 
8This document defines the **behavior and values** for AI agents working on this project.
9For detailed documentation, see [llms.txt](./llms.txt) and [ARCHITECTURE.md](./ARCHITECTURE.md).
10 
11## Project Identity
12 
13- **Type**: Multi-signature cryptocurrency wallet (BTC, BCH, ETH, XRP, ERC-20)
14- **Security Model**: Offline cold wallets (keygen, sign) + Online watch wallet
15- **Architecture**: Clean Architecture with strict layer separation
16- **Status**: Under refactoring based on Clean Code principles
17 
18## Core Values (Priority Order)
19 
201. **Security First** - Private key protection is non-negotiable
212. **Clean Architecture** - Domain layer has ZERO infrastructure dependencies
223. **Single Source of Truth (SSOT)** - One authoritative location for each piece of information
234. **Incremental Changes** - No breaking changes without rollback plan
245. **Code Quality** - Follow language-specific linting and testing standards
25 
26## Expected Behavior
27 
28### Always Do
29 
30- **Check current branch before starting any task** (see `git-workflow` skill)
31- Read relevant documentation before making changes
32- Run verification commands after code changes
33- Wrap errors with context using `fmt.Errorf("context: %w", err)`
34- Consider impact on offline wallet operations
35 
36### Never Do
37 
38- ❌ Log private keys or sensitive information
39- ❌ Edit files marked `DO NOT EDIT` (auto-generated)
40- ❌ Push directly to `main` branch
41- ❌ Run `git merge` or `gh pr merge`
42- ❌ Run `protoc` or `buf` commands directly (always use Makefile targets like `make proto`, `make proto-ts`)
43 
44### Ask Before
45 
46- Making security-related changes
47- Breaking changes to public APIs
48- Changes affecting multiple layers
49 
50## SSOT Structure
51 
52**When modifying rules, skills, or documentation, always edit the SSOT location.**
53 
54### AI Agent Configuration
55 
56| Category | SSOT Location | Other Locations |
57|----------|---------------|-----------------|
58| Rules | `.claude/rules/*.md` | `.cursor/rules/*.mdc` (auto-generated) |
59| Skills | `.claude/skills/*/SKILL.md` | `.cursor/skills/` (symlink) |
60| Commands | `.claude/commands/` | `.cursor/commands/` (reference only) |
61 
62**Sync Process:**
63 
64- `.cursor/rules/` → Auto-generated via `make sync-cursor-rules`
65- `.cursor/skills/` → Symlink to `.claude/skills/`
66 
67### Project Documentation
68 
69| Category | SSOT Location | Notes |
70|----------|---------------|-------|
71| Guidelines | `docs/guidelines/` | Coding, testing, security, workflow, database, code-generation |
72| Architecture | `ARCHITECTURE.md` | System design |
73| Agent behavior | `AGENTS.md` (this file) | Entry point for all agents |
74 
75### Key Principle
76 
77> **Don't Repeat Yourself (DRY)**: Define once, reference everywhere.
78> When information exists in multiple places, update the SSOT and reference it from others.
79 
80## Documentation Map
81 
82| Need | Document |
83|------|----------|
84| Project overview | [llms.txt](./llms.txt) |
85| Architecture design | [ARCHITECTURE.md](./ARCHITECTURE.md) |
86| **AI Agent instruction design** | [docs/ai/design.md](./docs/ai/design.md) |
87| **Guidelines** | [docs/guidelines/](./docs/guidelines) |
88| Coding conventions | [docs/guidelines/coding-conventions.md](./docs/guidelines/coding-conventions.md) |
89| Security | [docs/guidelines/security.md](./docs/guidelines/security.md) |
90| Testing | [docs/guidelines/testing.md](./docs/guidelines/testing.md) |
91| Workflow | [docs/guidelines/workflow.md](./docs/guidelines/workflow.md) |
92| Database changes | [docs/database/db-management.md](./docs/database/db-management.md) |
93| Auto-generated files | [docs/guidelines/code-generation.md](./docs/guidelines/code-generation.md) |
94| CLI commands | [internal/interface-adapters/cli/README.md](./internal/interface-adapters/cli/README.md) | Command × Chain × UseCase matrix (SSOT) |
95| Internal packages | [internal/AGENTS.md](./internal/AGENTS.md) |
96| Public packages | [pkg/AGENTS.md](./pkg/AGENTS.md) |
97 
98## Quick Reference
99 
100### Identifying BTC Address Types
101 
102| Prefix | Type | BIP | SegWit |
103|--------|------|-----|--------|
104| `1...` | P2PKH | BIP44 | ❌ |
105| `3...` | P2SH or P2SH-P2WPKH | BIP16/BIP49 | △ |
106| `bc1q...` | P2WPKH or P2WSH | BIP84 | ✅ |
107| `bc1p...` | P2TR (Taproot) | BIP86 | ✅ |
108 
109### Identifying BCH Address Types
110 
111| Prefix | Type | Multisig |
112|--------|------|----------|
113| `bitcoincash:q...` | P2PKH | ❌ |
114| `bitcoincash:p...` | P2SH | ✅ |
115 
116### Transaction Size Comparison
117 
118| Pattern | Weight | vBytes | Notes |
119|---------|--------|--------|-------|
120| P2PKH Single-sig (1-in, 2-out) | ~680 | ~170 | Legacy |
121| P2WPKH Single-sig (1-in, 2-out) | ~440 | ~110 | Native SegWit |
122| P2TR Single-sig (1-in, 2-out) | ~396 | ~99 | Taproot |
123| 2-of-3 P2WSH Multisig | ~1,100 | ~275 | Traditional Multisig |
124| 2-of-3 MuSig2 (P2TR) | ~560 | ~140 | Signature Aggregation |
125 
126---
127 
128## See Also
129 
130- [llms.txt](./llms.txt) - AI-friendly project sitemap
131- [ARCHITECTURE.md](./ARCHITECTURE.md) - System architecture
132- [docs/guidelines/](./docs/guidelines) - Project guidelines and standards
133