mary.my.id
Statusphere, but in atcute and SvelteKit
atproto
svelte
sveltekit
drizzle
atcute
typescript
chore: update agents.md
+68
-12
AGENTS.md
+68
-12
AGENTS.md
···
5
5
6
6
### project management
7
7
8
-
- tools like Node.js, Bun and pnpm are managed by mise, to run them, use `mise exec -- pnpm ...`
8
+
- pnpm is managed by mise, to run commands, use `mise exec -- pnpm ...`
9
+
- install dependencies with `pnpm install`
10
+
- run dev server with `pnpm dev`
11
+
- build with `pnpm build`
12
+
- preview production build with `pnpm preview`
13
+
- format via `pnpm run format` (prettier)
14
+
- lint via `pnpm run lint` (prettier --check)
15
+
- typecheck via `pnpm run check` (svelte-check)
16
+
- database commands: `pnpm db:push`, `pnpm db:generate`, `pnpm db:migrate`, `pnpm db:studio`
17
+
- check `pnpm view <package>` before adding a new dependency
9
18
10
19
### code writing
11
20
12
21
- new files should be in kebab-case
13
22
- use tabs for indentation, spaces allowed for diagrams in comments
14
23
- use single quotes and add trailing commas
15
-
- prefer arrow functions
24
+
- prefer arrow functions, but use regular methods in classes unless arrow functions are necessary
25
+
(e.g., when passing the method as a callback that needs `this` binding)
16
26
- use braces for control statements, even single-line bodies
17
27
- use bare blocks `{ }` to group related code and limit variable scope
18
28
- use template literals for user-facing strings and error messages
29
+
- avoid barrel exports (index files that re-export from other modules); import directly from source
30
+
- use `// #region <name>` and `// #endregion` to denote regions when a file needs to contain a lot
31
+
of code
32
+
- prefer required parameters over optional ones; optional parameters are acceptable when:
33
+
- the default is obvious and used by the vast majority of callers (e.g., `encoding = 'utf-8'`)
34
+
- it's a configuration value with a sensible default (e.g., `timeout = 5000`)
35
+
- avoid optional parameters that change behavioral modes or make the function do different things
36
+
based on presence/absence; prefer separate functions instead
37
+
- when adding optional parameters for backwards compatibility, consider whether a new function with
38
+
a clearer name would be better
19
39
20
40
### documentation
21
41
22
-
- documentations include README, code comments, commit messages, changesets
23
-
- any writing should be in lowercase, except for proper nouns, acronyms and 'I'
42
+
- documentations include README, code comments, commit messages
43
+
- any writing should be in lowercase, except for proper nouns, acronyms and 'I'; this does not apply
44
+
to public-facing interfaces like web UI
24
45
- only comment non-trivial code, focusing on _why_ rather than _what_
25
46
- write comments and JSDoc in lowercase (except proper nouns, acronyms, and 'I')
26
-
- add JSDoc comments to newly exported functions, methods, classes, fields, and enums
47
+
- add JSDoc comments to new publicly exported functions, methods, classes, fields, and enums
27
48
- JSDoc should include proper annotations:
28
49
- use `@param` for parameters (no dashes after param names)
29
50
- use `@returns` for return values
30
51
- use `@throws` for exceptions when applicable
31
52
- keep descriptions concise but informative
32
53
33
-
### misc
54
+
### agentic coding
34
55
35
-
- Claude Code's Bash tool persists directory changes (`cd`) across calls
36
-
- the `.research/` directory serves as a workspace for temporary experiments, analysis, and planning
37
-
materials. create it if necessary (it's gitignored). this directory may contain cloned
38
-
repositories or other reference materials that can help inform implementation decisions
56
+
- `.research/` directory in the project root serves as a workspace for temporary experiments,
57
+
analysis, and planning materials. create if not present (it's gitignored). this directory may
58
+
contain cloned repositories or other reference materials that can help inform implementation
59
+
decisions
60
+
- this document is intentionally incomplete; discover everything else in the repo
39
61
- don't make assumptions or speculate about code, plans, or requirements without exploring first;
40
62
pause and ask for clarification when you're still unsure after looking into it
41
-
- during plan mode, discuss the plans before finalizing/exiting plan mode to allow for additional
42
-
context or follow-up questions to be provided
63
+
- in plan mode, present the plan for review before exiting to allow for feedback or follow-up
64
+
questions
65
+
- when debugging problems, isolate the root cause first before attempting fixes: add logging,
66
+
reproduce the issue, narrow down the scope, and confirm the exact source of the problem
67
+
68
+
### Claude Code-specific
69
+
70
+
- Explore tool (subagents for exploration, planning, etc.) may not always be accurate; verify
71
+
subagent findings when needed
72
+
73
+
### cgr
74
+
75
+
use `@oomfware/cgr` to ask questions about external repositories.
76
+
77
+
```
78
+
npx @oomfware/cgr ask [options] <repo>[#branch] <question>
79
+
80
+
options:
81
+
-m, --model <model> model to use: opus, sonnet, haiku (default: haiku)
82
+
-d, --deep clone full history (enables git log/blame/show)
83
+
-w, --with <repo> additional repository to include, supports #branch (repeatable)
84
+
```
85
+
86
+
useful repositories:
87
+
88
+
- `github.com/sveltejs/kit` for SvelteKit framework, routing, load functions, hooks
89
+
- `github.com/sveltejs/svelte` for Svelte 5 reactivity, runes, components
90
+
- `github.com/mary-ext/atcute` for atcute AT Protocol client libraries
91
+
- `github.com/bluesky-social/atproto` for AT Protocol reference implementation
92
+
- `github.com/drizzle-team/drizzle-orm` for Drizzle ORM, database schema, queries
93
+
- `github.com/vitejs/vite` for Vite dev server, build tooling, plugin API
94
+
95
+
cgr works best with detailed questions. include file/folder paths when you know them, and reference
96
+
details from previous answers in follow-ups.
97
+
98
+
run `npx @oomfware/cgr --help` for more options.