mygo/AGENTS.md

AGENTS.md — MyGO

Project Layout

• Server: Go backend in the repository root, with documentation in docs/server/
• Web: React client in web/, with documentation in docs/web/
• Documentation index: docs/README.md

Agent Workflow

1. Read the task and identify the affected project
2. Read docs/README.md and the relevant project documentation for context
3. Explore existing code before writing new code
4. Implement following the relevant project conventions below
5. Run the verification commands for every affected project
6. Update the relevant project roadmap, decisions, architecture, or development documentation if anything changed

Server — Go Backend

Project Essentials

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

Repository Review

• Explicitly invoke $mygo-api-repo-review for repository-wide or scoped architecture, design, security, resilience, data-consistency, performance, and implementation audits.
• Repository reviews are read-only unless the user separately requests fixes.
• Use diff, main, or full review mode and optionally limit any mode with a target path, Go package, or logical component.

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/server/architecture.md	Adding new packages	Adding new packages
docs/server/decisions.md	Making technical decisions	Making technical decisions
docs/server/roadmap.md	Every server task	Completing a server feature
docs/server/development.md	Build/test/debug setup	Changing server 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

Server DO / DON'T

• DO put business logic in internal/, keep cmd/ thin
• 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 server work
• DON'T add, remove, or change Go module dependencies after debugging has started — ask for explicit permission first

Web — React Client

Project Essentials

• Source: web/
• Pure client-side rendered application; roadmap in docs/web/roadmap.md
• Stack: Node.js 24, Vite, React, TypeScript, React Router, TanStack Query, Tailwind CSS 4, and Ant Design
• Node.js version pinned in mise.toml

Documentation

File	Read Before	Update After
docs/web/decisions.md	Making Web technical decisions	Making Web technical decisions
docs/web/roadmap.md	Every Web task	Completing a Web feature or changing the Web plan

Commands

Run from web/:

npm ci                  # install locked dependencies
npm run dev             # start the development server
npm run check           # lint, type-check, and build

Git Version Control

• When using a worktree, create a new branch and place its worktree in .worktree/, naming safely (for example, git worktree add -b feat/partly-upload .worktree/feat-partly-upload).
• 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 the checks for every affected project; 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, 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:

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.

Shared DO / DON'T

• DO write all code, comments, and documentation in English
• DON'T commit without following the Git Version Control rules above

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