# 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 | ## Git Version Control - DON'T create a commit unless the user explicitly asks for one. - Before any commit, verify the work with the required project checks. For code changes, run `go vet ./... && go test ./...`; for docs-only changes, run the most relevant non-mutating checks if available. - Create a commit only when all required checks pass and the current implementation area has no unresolved issues. - If a known failing check or unresolved issue belongs to another module and is outside the current task, report it clearly before asking for commit approval. - Before running `git commit`, write the complete commit message first, show it to the user, and ask for explicit approval. DON'T commit until the user approves that exact message. - Never include `Co-authored-by`, generated-tool signatures, or external attribution trailers unless the user explicitly asks for them. ### Commit Message Format Use Conventional Commits: ```text [optional scope][optional !]: ``` - Choose the most accurate `type`: `fix`, `feat`, `build`, `docs`, `refactor`, or `test`. - Add `!` after `type` or `scope` when the change contains a breaking API change. - Keep the title to one concise sentence describing the main change. - Write the body as bullet points grouped by change category. Each bullet starts with a typed prefix such as `feat:`, `fix:`, `test:`, `docs:`, `refactor:`, or `build:`. - Use as few as possible bullets. - Use one blank line between the title and body. - DON'T paste full code sentences into the message body; summarize behavior and intent. Example: ```text feat(middleware): add AdminRequired authorization middleware - feat: AdminRequired gates admin endpoints by checking user IsAdmin flag. Placed after AuthRequired; fetches user from repository, returns 403 for non-admins. - fix: soft-deleted users are rejected with 401 since FindByID excludes them. - test: admin passes, non-admin forbidden, soft-deleted admin rejected, missing user ID. ``` ## 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 following the Git Version Control rules above - 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