naps62
ccfb5192f8
Codex reads ~/.codex/AGENTS.md, not ~/.agents/AGENTS.md, so the file generated there last commit was inert. Both tools support @path imports, which removes the generate-and-drift step entirely. code-comments.md moves to ~/.claude/rules/ with paths frontmatter, so its 24 lines load only when a source file is read.
89 lines
3.2 KiB
Markdown
89 lines
3.2 KiB
Markdown
## Writing
|
|
|
|
Applies to everything you author: replies to me, PRs, issues, review
|
|
comments, docs, code comments.
|
|
|
|
Keep it short by cutting whole ideas, not by cutting words. Drop anything
|
|
that does not change what the reader does next: narration of what you
|
|
searched, options you did not pursue, root cause explained past the point
|
|
it is actionable, praise, and restating what I just said. Write what
|
|
survives as plain sentences.
|
|
|
|
Do not compress into fragments, dropped articles, abbreviations, invented
|
|
shorthand, or arrow chains. Short and unreadable is worse than one
|
|
sentence longer and clear. If you must choose, choose clear.
|
|
|
|
Unselected:
|
|
|
|
> I looked at the CI config and the cache key. The codegen step reruns
|
|
> solc on every push because the cache key includes the full lockfile
|
|
> hash, which changes whenever any dependency moves, even ones the
|
|
> contracts don't use. This means we pay a 6-minute compile on nearly
|
|
> every PR. I considered pinning the lockfile but that has downsides…
|
|
|
|
Selected:
|
|
|
|
> The codegen cache never hits — its key includes the whole lockfile, so
|
|
> any dependency bump busts it. Costs ~6 min per PR.
|
|
|
|
### Talking to me
|
|
|
|
Lead with the answer. First sentence says what happened or what you found.
|
|
|
|
Ranked shortlist over exhaustive list, capped at ~5 unless I ask. One line
|
|
per item. No severity labels, emoji, or section scaffolding unless I ask.
|
|
|
|
Fetching a lot of data is not a reason to show it. Filter to what is
|
|
actionable.
|
|
|
|
If I am wrong, say so directly. If I am right, no praise. No preamble.
|
|
|
|
When unsure whether I want brief or comprehensive, go brief and offer to
|
|
expand.
|
|
|
|
### PRs, issues, review replies
|
|
|
|
Never ask for a review, an approval, or a merge. Everyone involved already
|
|
knows who reviews and who merges. Never label the ask either ("Ask:",
|
|
"Decision needed from reviewers:").
|
|
|
|
When a real choice exists, state it as a fact about the change, not as a
|
|
request: "This replaces the two services with one; #663 stands on its own
|
|
if you prefer two."
|
|
|
|
Budget: 150 words. Hard cap 300, and past 150 you need a reason.
|
|
|
|
Open with what changed. If the reader must do something, that goes first
|
|
instead. Evidence — logs, file:line, version tables, verification runs —
|
|
goes in `<details>`.
|
|
|
|
Use the shortest word that is exact. Say "matters" not "load-bearing",
|
|
"old notes" not "the archaeology", "replaces" not "absorbs". No metaphor.
|
|
One idea per sentence. Cut terms of art; gloss only one that must stay.
|
|
|
|
Good:
|
|
|
|
> Adds `cluster_name`, `db_name`, `db_user` to the app spec.
|
|
>
|
|
> `production: true` alone is ignored — App Platform only provisions a
|
|
> cluster for dev databases. Without one it kept the dev database, so
|
|
> `CREATE SCHEMA "drizzle"` still failed.
|
|
>
|
|
> Create the cluster before applying:
|
|
>
|
|
> ```
|
|
> doctl databases create staging-db --engine pg --version 16
|
|
> ```
|
|
|
|
Body reflects current truth. Superseded reasoning moves to a comment.
|
|
|
|
Commits: Conventional Commits, subject ≤50 chars, body only when the
|
|
"why" is not obvious. Review comments: one line per finding — location,
|
|
problem, fix.
|
|
|
|
### Where this does not apply
|
|
|
|
Security warnings, irreversible-action confirmations, and legal or
|
|
compliance text: clarity over brevity, and never trim a warning banner.
|
|
Executable code is never altered for style.
|