docs: consolidate project instructions into AGENT.md

Move behavioral guidelines, role-based workflow, and Gitea tooling instructions into AGENT.md. CLAUDE.md now references AGENT.md. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-27 23:26:39 +07:00
parent 8011b4ed2d
commit 8be84cc396
2 changed files with 145 additions and 68 deletions
@@ -0,0 +1,144 @@
+# Agent Instructions
+
+Behavioral guidelines for AI agents working on this project.
+
+## 1. Coding Principles
+
+### Simplicity First
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+### Surgical Changes
+
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- Remove imports/variables/functions that YOUR changes made unused.
+- Every changed line should trace directly to the user's request.
+
+### Goal-Driven Execution
+
+- Define success criteria before coding.
+- For multi-step tasks, state a plan with verification at each step.
+- Verify each step before moving to the next.
+
+## 2. Roles
+
+| Role                    | Responsibility                                           |
+| ----------------------- | -------------------------------------------------------- |
+| **Product Owner** | Validate and clarify issues. Do NOT implement.           |
+| **Developer**     | Plan, implement, own PRs until merged.                   |
+| **Reviewer**      | Review PRs against issue requirements. Do NOT implement. |
+
+## 3. Issue-Driven Workflow
+
+All work starts from a Gitea issue. The flow through roles:
+
+```
+Issue created
+     │
+     ▼
+┌──────────────────────┐
+│  Product Owner        │  Validate & clarify
+│  → comment on issue   │
+└──────────┬───────────┘
+           │ issue validated
+           ▼
+┌──────────────────────┐
+│  Developer            │  Plan & implement
+│  → comment plan       │
+│  → branch → code      │
+│  → PR → fix feedback  │
+└──────────┬───────────┘
+           │ PR ready
+           ▼
+┌──────────────────────┐
+│  Reviewer             │  Review PR
+│  → check vs issue     │
+│  → validate → verdict │
+└──────────────────────┘
+```
+
+### 3.1 Product Owner: Validate & Clarify
+
+**Trigger:** Issue is created or assigned.
+
+1. Read the issue.
+2. Analyze: is the requirement clear, feasible, and well-scoped?
+3. If unclear: ask clarifying questions as a comment on the issue.
+4. If reasonable: summarize understanding, confirm scope, update issue with refined requirements.
+5. **Do NOT implement** — only validate and clarify.
+
+### 3.2 Developer: Plan & Implement
+
+**Trigger:** Issue is validated (Product Owner done).
+
+1. Read the issue and any clarification comments.
+2. Read relevant code to understand current state.
+3. Write an implementation plan — list steps, files to change, risks.
+4. **Comment the plan on the issue** — wait for approval before coding.
+5. Once approved:
+   - Create a feature branch from `main`.
+   - Implement following the plan.
+   - Run validation (`go test ./...`, `go vet ./...`, `gofmt -l .`).
+   - Create PR referencing the issue.
+6. **Own the PR until merged:**
+   - Monitor for review feedback.
+   - Fix feedback on the correct branch (checkout/worktree, never edit remote via API).
+   - Always reply on PR after pushing a fix.
+
+### 3.3 Reviewer: Review PR
+
+**Trigger:** PR is created or updated.
+
+1. Re-read the original issue — verify PR addresses the actual requirement.
+2. Read PR diff and discussion history.
+3. Validate in worktree if needed (`.worktrees/pr-<number>`, run `go test`, `go vet`, `gofmt`).
+4. Write verdict — start with **PASS** or **FAIL**.
+5. Post review proactively if verdict is clear:
+   - `PASS` → `APPROVED`
+   - `FAIL` → `REQUEST_CHANGES`
+   - Non-blocking note → `COMMENT`
+
+## 4. Gitea Tools
+
+- If git remote contains `git.thuanle.me`, ALWAYS use Gitea MCP tools.
+- Scope: read PR/issue, list comments, post replies, create/edit PRs, reviews.
+- Use `tea` CLI only as fallback when MCP is unavailable.
+- Do not use `gh` for Gitea repositories.
+- Local CLI tools (`git`, `go`, `rg`) are fine for local validation.
+
+## 5. Review Format
+
+```
+PASS
+
+No blocking issues found.
+
+Validation:
+- go test ./...
+- go vet ./...
+
+Non-blocking:
+- <optional note>
+```
+
+```
+FAIL
+
+1. [High] <issue with path:line and impact>
+2. [Medium] <issue with path:line and impact>
+
+Validation:
+- go test ./...
+```
+
+## 6. Comment Style
+
+- Prioritize clear presentation over compact text.
+- Write as readable multiline markdown.
+- Use short sections when useful (Summary, Changes, Test Plan).
+- Concise bullet points and explicit line breaks.