MyGO/mygo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: restructure server and web documentation into ADR files and a

Browse Source 
routing table
This commit is contained in:
Sunday
2026-07-17 22:07:55 +08:00
parent f8494a44ca
commit 519aa35f1f
23 changed files with 710 additions and 654 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+91 -97
View File
@@ -2,146 +2,140 @@
## Project Layout
- Server: Go backend in the repository root, with documentation in `docs/server/`
- Web: React client in `web/`, with documentation in `docs/web/`
- Server: Go backend in the repository root
- Web: React client in `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
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
### Project Essentials
### 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.
- Module: `github.com/dhao2001/mygo`
- Go: 1.26.2, pinned in `mise.toml`
- CLI: Cobra
- Application code: `internal/`
- CLI composition: `cmd/`
### 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/`
- 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.
### 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
### Verification
```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
go fmt ./...
go build ./...
go test ./...
go vet ./...
```
### Server DO / DON'T
Run `go mod tidy` after adding or removing imports.
- 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
### 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
### Project Essentials
### 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`
- 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
### 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
### Verification
Run from `web/`:
```bash
npm ci # install locked dependencies
npm run dev # start the development server
npm run check # lint, type-check, and build
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
- 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.
- 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 title>
<type>[optional scope][optional !]: <description>
<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.
- 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.
Example:
## Shared Constraints
```text
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
- Write code, comments, and repository documentation in English.
- Follow the commit authorization workflow 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
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.