107 lines
4.9 KiB
Markdown
107 lines
4.9 KiB
Markdown
# 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
|
|
|
|
- Do not 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 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. Do not 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
|
|
<type>[optional scope]: <description title>
|
|
|
|
<body>
|
|
```
|
|
|
|
- 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 one blank line between the title and body, and one blank line between body bullets.
|
|
- Do not 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.
|
|
|
|
- feat: 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
|