docs(AGENTS.md): add Git Version Control section

2026-07-05 13:54:16 +08:00
parent 5eeb37389b
commit 17e346836c
1 changed files with 41 additions and 1 deletions
@@ -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
+<type>[optional scope]: <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 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