docs: reorganize documentation into server/ and web/ directories
- docs: move server docs to docs/server/ and update all cross-references - docs: move web-roadmap.md to docs/web/roadmap.md and create docs/web/decisions.md - docs: update AGENTS.md with separate Server and Web sections
This commit is contained in:
@@ -1,28 +1,36 @@
|
||||
# AGENTS.md — MyGO Backend
|
||||
# AGENTS.md — MyGO
|
||||
|
||||
## Project Essentials
|
||||
## Project Layout
|
||||
|
||||
- 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`
|
||||
- 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
|
||||
2. Read relevant `docs/` files for context
|
||||
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 conventions below
|
||||
5. Verify: `go vet ./... && go test ./...`
|
||||
6. Update `docs/roadmap.md`, `docs/decisions.md`, or `docs/architecture.md` if anything changed
|
||||
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
|
||||
|
||||
## Repository Review
|
||||
## 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
|
||||
### Go Conventions
|
||||
|
||||
- **Format**: `go fmt ./...` before every commit
|
||||
- **Imports**: stdlib / third-party / internal, blank-line separated
|
||||
@@ -32,19 +40,63 @@
|
||||
- **`init()`**: only in cobra cmd files for flag registration
|
||||
- **`cmd/`** is thin; business logic goes in `internal/`
|
||||
|
||||
## Documentation
|
||||
### 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 |
|
||||
| `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
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 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/`:
|
||||
|
||||
```bash
|
||||
npm ci # install locked dependencies
|
||||
npm run dev # start the development server
|
||||
npm run check # lint, type-check, and build
|
||||
```
|
||||
|
||||
## 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.
|
||||
- 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.
|
||||
@@ -78,25 +130,10 @@ feat(middleware): add AdminRequired authorization middleware
|
||||
- test: admin passes, non-admin forbidden, soft-deleted admin rejected, missing user ID.
|
||||
```
|
||||
|
||||
## Commands
|
||||
## Shared DO / DON'T
|
||||
|
||||
```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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user