thuanleandClaude Opus 4.7
8be84cc396
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>
145 lines
4.6 KiB
Markdown
145 lines
4.6 KiB
Markdown
# 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.
|