From 17e346836c83e78a3d2f6e67874e18877fe7ac28 Mon Sep 17 00:00:00 2001 From: Huxley Date: Sun, 5 Jul 2026 13:54:16 +0800 Subject: [PATCH] docs(AGENTS.md): add Git Version Control section --- AGENTS.md | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 27d43df..1bd3557 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,6 +35,46 @@ | `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 +[optional scope]: + + +``` + +- 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 @@ -52,7 +92,7 @@ go mod tidy # clean deps after add/remove - 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 explicit user request +- 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