142 lines
5.2 KiB
Markdown
142 lines
5.2 KiB
Markdown
# AGENTS.md — MyGO
|
|
|
|
## Project Layout
|
|
|
|
- Server: Go backend in the repository root
|
|
- Web: React client in `web/`
|
|
- Documentation index: `docs/README.md`
|
|
|
|
## Agent Workflow
|
|
|
|
1. Identify the affected project and required outcome.
|
|
2. Read `docs/README.md` and the relevant project documents.
|
|
3. Explore the existing code before making changes.
|
|
4. Follow the project conventions below.
|
|
5. Run the verification commands for every affected project.
|
|
6. Update documentation when architecture, workflow, decisions, or feature status changes.
|
|
|
|
## Documentation Routing
|
|
|
|
| Change | Read | Update |
|
|
|--------|------|--------|
|
|
| Server packages or boundaries | `docs/server/architecture.md` | When the current architecture changes |
|
|
| Server design or dependency decision | `docs/server/decisions.md` | When a decision is accepted or superseded |
|
|
| Server build, test, review, or config workflow | `docs/server/development.md` | When the workflow changes |
|
|
| Server feature scope or status | `docs/server/roadmap.md` | When capability status changes |
|
|
| Web design or tooling decision | `docs/web/decisions.md` | When a decision is accepted or superseded |
|
|
| Web feature scope or status | `docs/web/roadmap.md` | When capability status changes |
|
|
| Repository documentation | `docs/writing-guide.md` | When documentation policy changes |
|
|
|
|
Use the relevant decision index before making a significant architecture or dependency decision. Read only the ADRs relevant to the change.
|
|
|
|
## Server — Go Backend
|
|
|
|
### Essentials
|
|
|
|
- Module: `github.com/dhao2001/mygo`
|
|
- Go: 1.26.2, pinned in `mise.toml`
|
|
- CLI: Cobra
|
|
- Application code: `internal/`
|
|
- CLI composition: `cmd/`
|
|
|
|
### Go Conventions
|
|
|
|
- Separate imports into standard library, third-party, and internal groups.
|
|
- Wrap errors with operation context: `fmt.Errorf("operation: %w", err)`.
|
|
- Pass `context.Context` first in I/O, storage, and lifecycle functions.
|
|
- Add doc comments to exported names.
|
|
- Keep business logic in `internal/`; keep `cmd/` focused on CLI composition and startup.
|
|
- Add required Go module dependencies before writing code that imports them.
|
|
|
|
### Verification
|
|
|
|
```bash
|
|
go fmt ./...
|
|
go build ./...
|
|
go test ./...
|
|
go vet ./...
|
|
```
|
|
|
|
Run `go mod tidy` after adding or removing imports.
|
|
|
|
### Repository Review
|
|
|
|
Invoke `$mygo-api-repo-review` for repository-wide or scoped architecture, design, security, resilience, data-consistency, performance, and implementation audits.
|
|
|
|
- `diff`: compare the workspace, including relevant untracked files, with `HEAD`.
|
|
- `main`: compare the workspace with the merge base of `HEAD` and local `main`.
|
|
- `full`: review the complete repository.
|
|
|
|
Reviews are read-only unless the user also requests fixes. A mode can target a path, Go package, or logical component.
|
|
|
|
### Server Constraints
|
|
|
|
- Do not load the complete `go.sum` file into context. Use `rg` to find the required module or version entry.
|
|
- Dependency changes made after debugging begins require explicit user approval.
|
|
- Complete `go vet ./...` before finishing server code changes.
|
|
|
|
## Web — React Client
|
|
|
|
### Essentials
|
|
|
|
- Source: `web/`
|
|
- Node.js: 24, pinned in `mise.toml`
|
|
- Rendering: client-side Vite application
|
|
- Stack: React, TypeScript, React Router, TanStack Query, Tailwind CSS 4, and Ant Design
|
|
|
|
### Verification
|
|
|
|
Run from `web/`:
|
|
|
|
```bash
|
|
npm ci
|
|
npm run check
|
|
```
|
|
|
|
Use `$playwright-cli` for browser inspection and debugging. Run the repository wrapper from `web/`:
|
|
|
|
```bash
|
|
mise exec -- npm run playwright:cli -- <command>
|
|
```
|
|
|
|
Do not invoke Playwright through a global installation or a floating `npx` package.
|
|
|
|
## Git Version Control
|
|
|
|
- Place worktrees under `.worktree/` and use a safe branch name, for example `git worktree add -b feat/partly-upload .worktree/feat-partly-upload`.
|
|
- Create a commit only when the user explicitly requests one.
|
|
- Run the required checks before proposing a commit. For documentation-only changes, run the relevant documentation checks.
|
|
- Resolve implementation issues in the affected area before proposing a commit. Report unrelated known failures separately.
|
|
- Write the complete commit message and obtain explicit approval for that exact message before running `git commit`.
|
|
- Commit messages contain no `Co-authored-by`, generated-tool signatures, or attribution trailers unless the user requests them.
|
|
|
|
### Commit Message Format
|
|
|
|
Use Conventional Commits:
|
|
|
|
```text
|
|
<type>[optional scope][optional !]: <description>
|
|
|
|
<body>
|
|
```
|
|
|
|
- Use `fix`, `feat`, `build`, `docs`, `refactor`, or `test` as the type.
|
|
- Add `!` for a breaking API change.
|
|
- Keep the title concise.
|
|
- Write the body as a small set of bullets with typed prefixes such as `feat:`, `fix:`, `test:`, or `docs:`.
|
|
- Leave one blank line between the title and body.
|
|
- Summarize behavior and intent instead of copying code statements.
|
|
|
|
## Shared Constraints
|
|
|
|
- Write code, comments, and repository documentation in English.
|
|
- Follow the commit authorization workflow above.
|
|
|
|
## Debugging Principles
|
|
|
|
1. Confirm that the test expresses the intended behavior.
|
|
2. Correct the test when its expectation is wrong.
|
|
3. Correct the implementation when the test is valid.
|
|
4. Preserve intended assertions and edge-case coverage. Never weaken a valid test to make it pass.
|
|
5. Stop after six unsuccessful debugging rounds and report the current evidence.
|