AGENTS.md

1# AGENTS.md
2 
3These instructions apply to the entire repository.
4 
5## Stack
6 
7- Use Node.js 20.9.0 or newer.
8- App is Next.js portfolio site with page routes under `pages/`.
9- Shared UI lives under `components/`.
10- Extracted design-system primitives live under `components/design-system/`.
11- Static assets live under `static/`.
12- Static export output lives under `out/`.
13 
14## Design Context
15 
16- Read `PRODUCT.md` before making UX, copy, or layout decisions.
17- Read `DESIGN.md` before changing colors, type, spacing, elevation, or component styling.
18- Reuse existing tokens and primitives from `components/design-system/` before adding new hard-coded values.
19- Keep portfolio feel aligned with current design direction: light paper background, Trirong + Rubik typography, selective project accent colors, soft shadows, restrained motion.
20 
21## Working Rules
22 
23- Prefer small, low-churn edits over broad rewrites.
24- When a visual pattern is repeated 3+ times, extract into `components/design-system/` or an existing shared component instead of duplicating it again.
25- Avoid modifying `package-lock.json` unless dependency work requires it.
26- If you change source UI code, do not hand-edit `out/`; regenerate via build.
27 
28## Verification
29 
30- After making code changes, run:
31```bash
32  npm test
33  npm run build
34```
35- Ensure both commands succeed before committing.
36- `npm run build` performs static export and refreshes `out/`, including `out/.nojekyll`.
37 
38## Repo Notes
39 
40- `npm run build` is cross-platform. Keep it that way; do not reintroduce Windows-only shell snippets.
41- Repository contains generated static HTML at root and under `out/`. Treat `pages/` and `components/` as source of truth.
42- Jest tests live under `components/__tests__/`.
43 
44## Commits
45 
46- Follow Conventional Commits for commit messages.
47 
48 
49## Scope control
50 
51Before editing, inspect the repository state:
52 
53- Run `git status —short`
54- Run `git diff —stat`
55- If the diff is large, identify the largest changed files before editing.
56 
57## Generated files
58 
59Do not edit, stage, commit, or include generated output unless explicitly instructed.
60 
61Treat these paths as generated:
62 
63- `out/**`
64- `.next/**`
65- `dist/**`
66- `build/**`
67- `coverage/**`
68- `.turbo/**`
69- `.vercel/**`
70- `node_modules/**`
71- `*.map`
72- `*.min.js`
73- `*.min.css`
74- generated lockfile churn not directly related to the requested change
75 
76If a build command modifies generated files, leave them unstaged and report that they changed.
77 
78## Commit and diff hygiene
79 
80Keep changes small and source-focused.
81 
82Prefer changing:
83 
84- `src/**`
85- `app/**`
86- `pages/**`
87- `components/**`
88- `public/**` only when actual static assets intentionally change
89- config files only when required
90 
91Avoid mixing:
92 
93- source changes
94- formatting-only changes
95- dependency updates
96- generated build output
97- deployment artifacts
98 
99If deployment output is required, make it a separate deployment-only commit or branch, not part of the implementation diff.
100 
101## Next.js / GitHub Pages
102 
103For normal development tasks, do not commit `out/`.
104 
105`out/` is deployment output, not source code. If GitHub Pages deployment needs it, use a separate deploy workflow, deploy branch, or explicit deployment step.
106 
107 
108Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
109 
110**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
111 
112## 1. Think Before Coding
113 
114**Don't assume. Don't hide confusion. Surface tradeoffs.**
115 
116Before implementing:
117- State your assumptions explicitly. If uncertain, ask.
118- If multiple interpretations exist, present them - don't pick silently.
119- If a simpler approach exists, say so. Push back when warranted.
120- If something is unclear, stop. Name what's confusing. Ask.
121 
122## 2. Simplicity First
123 
124**Minimum code that solves the problem. Nothing speculative.**
125 
126- No features beyond what was asked.
127- No abstractions for single-use code.
128- No "flexibility" or "configurability" that wasn't requested.
129- No error handling for impossible scenarios.
130- If you write 200 lines and it could be 50, rewrite it.
131 
132Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
133 
134## 3. Surgical Changes
135 
136**Touch only what you must. Clean up only your own mess.**
137 
138When editing existing code:
139- Don't "improve" adjacent code, comments, or formatting.
140- Don't refactor things that aren't broken.
141- Match existing style, even if you'd do it differently.
142- If you notice unrelated dead code, mention it - don't delete it.
143 
144When your changes create orphans:
145- Remove imports/variables/functions that YOUR changes made unused.
146- Don't remove pre-existing dead code unless asked.
147 
148The test: Every changed line should trace directly to the user's request.
149 
150## 4. Goal-Driven Execution
151 
152**Define success criteria. Loop until verified.**
153 
154Transform tasks into verifiable goals:
155- "Add validation" → "Write tests for invalid inputs, then make them pass"
156- "Fix the bug" → "Write a test that reproduces it, then make it pass"
157- "Refactor X" → "Ensure tests pass before and after"
158 
159For multi-step tasks, state a brief plan:
160```
1611. [Step] → verify: [check]
1622. [Step] → verify: [check]
1633. [Step] → verify: [check]
164```
165 
166Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
167 
168---
169 
170**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.
171