diff --git a/AGENT.md b/AGENT.md new file mode 100644 index 0000000..331f2a6 --- /dev/null +++ b/AGENT.md @@ -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-`, 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: +- +``` + +``` +FAIL + +1. [High] +2. [Medium] + +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. diff --git a/CLAUDE.md b/CLAUDE.md index 66cd1ae..ffc2a95 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,70 +1,3 @@ # CLAUDE.md -Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed. - -**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment. - -## 1. Think Before Coding - -**Don't assume. Don't hide confusion. Surface tradeoffs.** - -Before implementing: - -- State your assumptions explicitly. If uncertain, ask. -- If multiple interpretations exist, present them - don't pick silently. -- If a simpler approach exists, say so. Push back when warranted. -- If something is unclear, stop. Name what's confusing. Ask. - -## 2. Simplicity First - -**Minimum code that solves the problem. Nothing speculative.** - -- No features beyond what was asked. -- No abstractions for single-use code. -- No "flexibility" or "configurability" that wasn't requested. -- No error handling for impossible scenarios. -- If you write 200 lines and it could be 50, rewrite it. - -Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. - -## 3. Surgical Changes - -**Touch only what you must. Clean up only your own mess.** - -When editing existing code: - -- 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. -- If you notice unrelated dead code, mention it - don't delete it. - -When your changes create orphans: - -- Remove imports/variables/functions that YOUR changes made unused. -- Don't remove pre-existing dead code unless asked. - -The test: Every changed line should trace directly to the user's request. - -## 4. Goal-Driven Execution - -**Define success criteria. Loop until verified.** - -Transform tasks into verifiable goals: - -- "Add validation" → "Write tests for invalid inputs, then make them pass" -- "Fix the bug" → "Write a test that reproduces it, then make it pass" -- "Refactor X" → "Ensure tests pass before and after" - -For multi-step tasks, state a brief plan: - -``` -1. [Step] → verify: [check] -2. [Step] → verify: [check] -3. [Step] → verify: [check] -``` - -Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. - ---- - -**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes. +See [AGENT.md](AGENT.md) for full project instructions and workflow.