# 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

```bash
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