4.9 KiB
4.9 KiB
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
- Read the task
- Read relevant
docs/files for context - Explore existing code before writing new code
- Implement following the conventions below
- Verify:
go vet ./... && go test ./... - Update
docs/roadmap.md,docs/decisions.md, ordocs/architecture.mdif 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 registrationcmd/is thin; business logic goes ininternal/
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:
<type>[optional scope][optional !]: <description title>
<body>
- Choose the most accurate
type:fix,feat,build,docs,refactor, ortest. - Add
!aftertypeorscopewhen 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:, orbuild:. - 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:
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
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/, keepcmd/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.sumentirely into context — usegrepor 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:
- Examine the test first — ensure the test code correctly expresses the intended program behavior
- Fix the test if it's wrong — if the test doesn't represent correct expected behavior, correct the test to match the intended behavior
- Fix the implementation if the test is correct — only after confirming the test is valid, locate and fix the bug in the implementation
- 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
- 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