mygo/AGENTS.md

AGENTS.md — MyGO Backend

Project Essentials

• Module: github.com/dhao2001/mygo, Go 1.26.2
• WebDisk (cloud drive) backend; roadmap in docs/roadmap.md
• CLI framework: github.com/spf13/cobra
• Go version pinned in mise.toml

Agent Workflow

1. Read the task
2. Read relevant docs/ files for context
3. Explore existing code before writing new code
4. Implement following the conventions below
5. Verify: go vet ./... && go test ./...
6. Update docs/roadmap.md, docs/decisions.md, or docs/architecture.md if anything changed

Go Conventions

• Format: go fmt ./... before every commit
• Imports: stdlib / third-party / internal, blank-line separated
• Errors: wrap with fmt.Errorf("context: %w", err)
• Context: first param in I/O, storage, lifecycle funcs
• Exported names: doc-commented
• init(): only in cobra cmd files for flag registration
• cmd/ is thin; business logic goes in internal/

Documentation

File	Read Before	Update After
docs/architecture.md	Adding new packages	Adding new packages
docs/decisions.md	Making technical decisions	Making technical decisions
docs/roadmap.md	Every task	Completing a feature
docs/development.md	Build/test/debug setup	Changing workflow

Commands

go build ./...          # build all packages
go test ./...           # all tests
go vet ./...            # static analysis
go fmt ./...            # format
go mod tidy             # clean deps after add/remove

DO / DON'T

• DO put business logic in internal/, keep cmd/ thin
• DO write all code, comments, and documentation in English
• DO add all Go module dependencies before writing code that uses them
• DON'T read go.sum entirely into context — use grep or other tools to search specific patterns if needed
• DON'T skip go vet ./... before finishing work
• DON'T commit without explicit user request
• DON'T add, remove, or change Go module dependencies after debugging has started — ask for explicit permission first

Debugging Principles

When a test failure occurs, follow this strict order:

1. Examine the test first — ensure the test code correctly expresses the intended program behavior
2. Fix the test if it's wrong — if the test doesn't represent correct expected behavior, correct the test to match the intended behavior
3. Fix the implementation if the test is correct — only after confirming the test is valid, locate and fix the bug in the implementation
4. Never weaken tests to gain passing status — do not relax assertions, remove edge cases, or simplify test logic just to make tests pass. Tests exist to catch problems, not to produce a 100% pass rate
5. Escalate after 6 rounds — if a problem remains unresolved after 6 debugging attempts, stop and report the current state to the user for further investigation