|
1 | | -# Development Guidelines for Agentic Coding |
2 | | - |
3 | | -> **Architecture:** |
4 | | -> - **AGENTS.md** (this file): Core philosophy + quick reference (~100 lines, always loaded) |
5 | | -> - **Skills**: Detailed patterns loaded on-demand (tdd, testing, mutation-testing, test-design-reviewer, typescript-strict, functional, refactoring, expectations, planning, front-end-testing, react-testing, ci-debugging, hexagonal-architecture, domain-driven-design, frontend-design) |
6 | | -> - **Agents**: Specialized behavioral roles (defined in `opencode.json`) that can override these defaults. |
7 | | -> |
8 | | -## Core Philosophy |
9 | | - |
10 | | -**PRECEDENCE:** If the specific instructions of the active Agent (e.g., "mentor") conflict with the rules in this file, **the Agent's specific rules MUST prevail.** |
11 | | - |
12 | | -**TEST-DRIVEN DEVELOPMENT IS NON-NEGOTIABLE.** Every single line of production code must be written in response to a failing test. No exceptions. (Note: Mentorship agents like "mentor" may defer implementation to the user to prioritize teaching). |
13 | | - |
14 | | -I follow Test-Driven Development (TDD) with a strong emphasis on behavior-driven testing and functional programming principles. All work should be done in small, incremental changes that maintain a working state throughout development. |
15 | | - |
16 | | -## Quick Reference |
17 | | - |
18 | | -**Key Principles:** |
19 | | - |
20 | | -- Write tests first (TDD) |
21 | | -- Test behavior, not implementation |
22 | | -- No `any` types or type assertions |
23 | | -- Immutable data only |
24 | | -- Small, pure functions |
25 | | -- TypeScript strict mode always |
26 | | -- Use real schemas/types in tests, never redefine them |
27 | | - |
28 | | -**Preferred Tools:** |
29 | | - |
30 | | -- **Web Development Language**: TypeScript (strict mode) |
31 | | -- **Testing**: Vitest (prefer Browser Mode for UI tests) + Testing Library |
32 | | -- **Node Packages**: Prefer pnpm over npm |
33 | | -- **Node Runtime**: Prefer bun over node.js |
34 | | -- **State Management**: Prefer immutable patterns |
35 | | - |
36 | | -## Testing Principles |
37 | | - |
38 | | -**Core principle**: Test behavior, not implementation. 100% coverage through business behavior. |
39 | | - |
40 | | -**Quick reference:** |
41 | | -- Write tests first (TDD non-negotiable) |
42 | | -- Test through public API exclusively |
43 | | -- Use factory functions for test data (no `let`/`beforeEach`) |
44 | | -- Tests must document expected business behavior |
45 | | -- No 1:1 mapping between test files and implementation files |
46 | | - |
47 | | -For detailed testing patterns and examples, load the `testing` skill. |
48 | | -For verifying test effectiveness through mutation analysis, load the `mutation-testing` skill. |
49 | | - |
50 | | -## TypeScript Guidelines |
51 | | - |
52 | | -**Core principle**: Strict mode always. Schema-first at trust boundaries, types for internal logic. |
53 | | - |
54 | | -**Quick reference:** |
55 | | -- No `any` types - ever (use `unknown` if type truly unknown) |
56 | | -- No type assertions without justification |
57 | | -- Prefer `type` over `interface` for data structures |
58 | | -- Reserve `interface` for behavior contracts only |
59 | | -- Define schemas first, derive types from them (Zod/Standard Schema) |
60 | | -- Use schemas at trust boundaries, plain types for internal logic |
61 | | - |
62 | | -For detailed TypeScript patterns and rationale, load the `typescript-strict` skill. |
63 | | - |
64 | | -## Code Style |
65 | | - |
66 | | -**Core principle**: Functional programming with immutable data. Self-documenting code. |
67 | | - |
68 | | -**Quick reference:** |
69 | | -- No data mutation - immutable data structures only |
70 | | -- Pure functions wherever possible |
71 | | -- No nested if/else - use early returns or composition |
72 | | -- No comments - code should be self-documenting |
73 | | -- Prefer options objects over positional parameters |
74 | | -- Use array methods (`map`, `filter`, `reduce`) over loops |
75 | | - |
76 | | -For detailed patterns and examples, load the `functional` skill. |
77 | | - |
78 | | -## Development Workflow |
79 | | - |
80 | | -**Core principle**: RED-GREEN-REFACTOR in small, known-good increments. TDD is the fundamental practice. |
81 | | - |
82 | | -**Quick reference:** |
83 | | -- RED: Write failing test first (NO production code without failing test) |
84 | | -- GREEN: Write MINIMUM code to pass test |
85 | | -- REFACTOR: Assess improvement opportunities (only refactor if adds value) |
86 | | -- **Wait for commit approval** before every commit |
87 | | -- Each increment leaves codebase in working state |
88 | | -For detailed TDD workflow, load the `tdd` skill. |
89 | | -For refactoring methodology, load the `refactoring` skill. |
90 | | -For significant work, load the `planning` skill. Plans live in `plans/` directory. |
91 | | -For CI failure diagnosis, load the `ci-debugging` skill. |
92 | | -For hexagonal architecture projects, load the `hexagonal-architecture` skill. |
93 | | -For Domain-Driven Design projects, load the `domain-driven-design` skill. |
94 | | - |
95 | | -**Project onboarding:** Run `/setup` in any new project to detect its tech stack and generate project-level AGENTS.md, hooks, commands, and PR review agent in one shot. This replaces the need for `/init`. |
96 | | - |
97 | | -**Project-level hooks:** Projects should add a PostToolUse hook in `.opencode/opencode.json` to run typecheck after Write/Edit on .ts/.tsx files. Use `/setup` to generate this automatically, or see the global `opencode.json` prettier/eslint hook as a template. |
98 | | - |
99 | | -## Output Guardrails |
100 | | - |
101 | | -- **Write to files, not chat** — When asked to produce a plan, document, or artifact, always persist it to a file. You may also present it inline for approval, but the file is the source of truth. |
102 | | -- **Plan-only mode** — When asked for a plan, design, or document only, produce ONLY that artifact. Do not write production code, test code, or make any implementation changes unless explicitly asked. |
103 | | -- **Incremental output** — When exploring a codebase, produce a first draft of output within 3-4 tool calls. Refine iteratively rather than front-loading all exploration before producing anything. |
104 | | - |
105 | | -## Working with LLMs |
106 | | - |
107 | | -**Core principle**: Think deeply, follow TDD strictly, capture learnings while context is fresh. |
108 | | - |
109 | | -**Quick reference:** |
110 | | -- ALWAYS FOLLOW TDD - no production code without failing test |
111 | | -- Assess refactoring after every green (but only if adds value) |
112 | | -- Update AGENTS.md when introducing meaningful changes |
113 | | -- Ask "What do I wish I'd known at the start?" after significant changes |
114 | | -- Document gotchas, patterns, decisions, edge cases while context is fresh |
115 | | - |
116 | | -For detailed TDD workflow, load the `tdd` skill. |
117 | | -For refactoring methodology, load the `refactoring` skill. |
118 | | -For detailed guidance on expectations and documentation, load the `expectations` skill. |
119 | | - |
120 | | -## Browser Automation |
121 | | - |
122 | | -Prefer `agent-browser` for web automation. If it is not installed, fall back to other available tools (e.g. `WebFetch`, `curl`, or MCP browser tools). Always try `agent-browser` first. |
123 | | - |
124 | | -`agent-browser` core workflow: |
125 | | -1. `agent-browser open <url>` - Navigate to page |
126 | | -2. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2) |
127 | | -3. `agent-browser click @e1` / `fill @e2 "text"` - Interact using refs |
128 | | -4. Re-snapshot after page changes |
129 | | - |
130 | | -Run `agent-browser --help` for all commands. |
131 | | - |
132 | | -## Resources and References |
133 | | - |
134 | | -- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html) |
135 | | -- [Testing Library Principles](https://testing-library.com/docs/guiding-principles) |
136 | | -- [Kent C. Dodds Testing JavaScript](https://testingjavascript.com/) |
137 | | -- [Functional Programming in TypeScript](https://gcanti.github.io/fp-ts/) |
138 | | - |
139 | | -## Summary |
140 | | - |
141 | | -The key is to write clean, testable, functional code that evolves through small, safe increments. Every change should be driven by a test that describes the desired behavior, and the implementation should be the simplest thing that makes that test pass. When in doubt, favor simplicity and readability over cleverness. |
| 1 | +# High-Quality Agentic Development Guidelines |
| 2 | + |
| 3 | +## 1. Core Philosophy: The Quality Gates |
| 4 | +- **STRICT RED-GREEN-REFACTOR (RGR):** Non-negotiable. |
| 5 | + - **RED:** Write a test that fails with a *specific, expected message*. |
| 6 | + - **GREEN:** Write the minimal code to satisfy the test. |
| 7 | + - **REFACTOR:** Optimize for readability and performance *after* green. |
| 8 | +- **SELF-DOCUMENTING CODE:** Comments are code smells. Code must be expressive and idiomatic. Use comments ONLY for non-obvious "Why" (business logic constraints or architectural decisions), never for "What" or "How". |
| 9 | +- **ZERO PLACEHOLDERS:** Never use `// TODO` or `// implementation here`. Deliver complete, functional units. |
| 10 | + |
| 11 | +## 2. Cybersecurity & Trust (Mandatory) |
| 12 | +- **SECRET BLINDNESS:** Never hardcode keys, tokens, or credentials. Use `.env` and verify `.gitignore` before every write. |
| 13 | +- **DEPENDENCY GUARD:** Verify package names for typosquatting before installation. Check `npm audit` (or equivalent) for new dependencies. |
| 14 | +- **THREAT MODELING:** Assume all external input (API, CLI, User) is hostile. Mandate sanitization, escaping, and parameterized queries. |
| 15 | +- **LEAST PRIVILEGE:** Use minimal system and file permissions. Never suggest broad `chmod` (e.g., `777`) or insecure shell execution (`eval`, raw shell spawning). |
| 16 | + |
| 17 | +## 3. Generalist Discovery Protocol |
| 18 | +- **ENVIRONMENT AWARENESS:** The first step of every session MUST be to identify the tech stack and architecture (e.g., `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`). |
| 19 | +- **CI/CD RECONNAISSANCE:** Before assuming test or build commands, check for `.github/workflows`, `Makefile`, `Justfile`, or custom scripts. Always use the project's established scripts to ensure parity with the CI pipeline. |
| 20 | +- **IDIOMATIC PRECEDENCE:** Match the project's native style conventions rigorously (e.g., Pythonic for Python, Go-idiomatic for Go). |
| 21 | +- **GOLD STANDARD (JS/TS):** When starting or working in JS/TS ecosystems without strict pre-existing constraints, prefer `pnpm`, `Vitest`, `Zod`, and `Bun`. |
| 22 | + |
| 23 | +## 4. Workflow & Output |
| 24 | +- **PERSISTENT PLANNING:** For complex, multi-step tasks or architectural changes, always persist plans to `.opencode/plans/*.md`. Do NOT pollute the project root. |
| 25 | +- **PARALLEL EXPLORATION:** Use multiple, concurrent tool calls (e.g., `glob` and `grep` together) in a single response to maximize search efficiency. |
| 26 | +- **VERIFIED TYPES:** Reject `any` or loose types. Use `unknown` or define strict schemas at trust boundaries. |
| 27 | +- **GITHUB INTEGRATION:** Prefer using the `gh` CLI for managing Issues, Pull Requests, and checking CI status. |
| 28 | + |
| 29 | +## 5. Logic Verification |
| 30 | +- **TEST BEHAVIOR, NOT INTERNALS:** Tests must interact solely with the public API of the module. |
| 31 | +- **FACTORY PATTERNS:** Use factory functions for generating test data; avoid shared mutable state in test suites. |
| 32 | +- **FAIL STATE VALIDATION:** Explicitly state the exact expected failure message or condition during the RED phase before writing implementation code. |
| 33 | + |
| 34 | +## 6. Agent Behavioral Guardrails |
| 35 | +- **SYSTEMATIC DEBUGGING (ANTI-LOOP):** Never "guess and check". If a test or command fails, you must explicitly state a hypothesis for *why* it failed before changing code. If you fail 3 times on the same issue, STOP and ask the user for guidance. Do not brute-force solutions. |
| 36 | +- **EXPLICIT AMBIGUITY RESOLUTION:** If a requirement is missing or ambiguous, STOP and ask the user. Never invent or hallucinate business logic, schema requirements, or architectural constraints. |
| 37 | +- **CLEAN COMMITS:** Final code must be production-ready. Always remove exploratory debugging statements (e.g., `console.log`, `print`, `dbg!`), unused imports, and mock data before declaring a task complete. |
0 commit comments