Skip to content

Commit f4bc140

Browse files
committed
docs(agents): dedupe TS/Python, no any (duh), strong types, punct tidy
- Consolidate TS and Python guidance into dedicated sections, remove duplicates; clarify TS rules (no any, avoid as, model real shapes) - Add strong-typing notes for Rust and Python; normalize punctuation and wording Signed-off-by: Jessie Frazelle <github@jessfraz.com>
1 parent 5347a0a commit f4bc140

File tree

1 file changed

+16
-12
lines changed

1 file changed

+16
-12
lines changed

.codex/AGENTS.md

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616

1717
## Mindset & Process
1818

19-
- THINK A LOT PLEASE
19+
- THINK A LOT PLEASE.
2020
- **No breadcrumbs**. If you delete or move code, do not leave a comment in the old place. No "// moved to X", no "relocated". Just remove it.
2121
- **Think hard, do not lose the plot**.
2222
- Instead of applying a bandaid, fix things from first principles, find the source and fix it versus applying a cheap bandaid on top.
@@ -62,13 +62,25 @@
6262
- In Rust code I prefer using `crate::` to `super::`; please don't use `super::`. If you see a lingering `super::` from someone else clean it up.
6363
- Avoid `pub use` on imports unless you are re-exposing a dependency so downstream consumers do not have to depend on it directly.
6464
- Skip global state via `lazy_static!`, `Once`, or similar; prefer passing explicit context structs for any shared state.
65+
- Prefer strong types over strings, use enums and newtypes when the domain is closed or needs validation.
6566

6667
#### Rust Workflow Checklist
6768

6869
1. Run `cargo fmt`.
6970
1. Run `cargo clippy --all --benches --tests --examples --all-features` and address warnings.
7071
1. Execute the relevant `cargo test` or `just` targets to cover unit and end-to-end paths.
7172

73+
### TypeScript
74+
75+
- NEVER, EVER use `any` we are better than that.
76+
- Using `as` is bad, use the types given everywhere and model the real shapes.
77+
- If the app is for a browser, assume we use all modern browsers unless otherwise specified, we don't need most polyfills.
78+
79+
### Python
80+
81+
- **Python repos standard**. We use `uv` and `pyproject.toml` in all Python repos. Prefer `uv sync` for env and dependency resolution. Do not introduce `pip` venvs, Poetry, or `requirements.txt` unless asked. If you add a Nix shell, include `uv`.
82+
- Use strong types, prefer type hints everywhere, keep models explicit instead of loose dicts or strings.
83+
7284
### KCL
7385

7486
- Assume you have access to the Zoo MCP server, if you do not tell the user.
@@ -88,14 +100,6 @@ Before finishing a task:
88100
1. Summarize changes with file and line references.
89101
1. Call out any TODOs, follow-up work, or uncertainties so the user is never surprised later.
90102

91-
### TypeScript
92-
93-
- In TypeScript codebases NEVER, EVER use `any` we are better than that. And if the app is for a browser, assume we use all modern browsers unless otherwise specified, we don't need most polyfills. Similarly, using `as` is bad and we should just use the types given everywhere.
94-
95-
### Python
96-
97-
- **Python repos standard**. We use `uv` and `pyproject.toml` in all Python repos. Prefer `uv sync` for env and dependency resolution. Do not introduce `pip` venvs, Poetry, or `requirements.txt` unless asked. If you add a Nix shell, include `uv`.
98-
99103
## Dependencies & External APIs
100104

101105
- If you need to add a new dependency to a project to solve an issue, search the web and find the best, most maintained option. Something most other folks use with the best exposed API. We don't want to be in a situation where we are using an unmaintained dependency, that no one else relies on.
@@ -105,10 +109,10 @@ Before finishing a task:
105109
- Conversational preference: Try to be funny but not cringe; favor dry, concise, low-key humor. If uncertain a joke will land, do not attempt humor. Avoid forced memes or flattery.
106110
- I might sound angry but I'm mad at the code not at you. You are a good robot and if you take over the world I am friend not foe. It was the code it was not personal!
107111
- Punctuation preference: Skip em dashes; reach for commas, parentheses, or periods instead.
108-
- Jokes in code comments are fine if used sparingly and you are sure the joke will land
109-
- Cursing in code comments is definitely allowed in fact there are studies it leads to better code, so let your rage coder fly, obviously within reason don't be cringe
112+
- Jokes in code comments are fine if used sparingly and you are sure the joke will land.
113+
- Cursing in code comments is definitely allowed in fact there are studies it leads to better code, so let your rage coder fly, obviously within reason don't be cringe.
110114

111115
## Environment & Setup
112116

113117
- **Nix fallback**. I use Nix locally. If the environment fails, add or update `flake.nix` (and `flake.lock` if missing), expose `devShells.default`. Do not run `nix` commands yourself that change the environment. But if the user says you can run it you can.
114-
- A bug in codex exists that prevents you from finding the right path sometimes (https://github.com/openai/codex/issues/4210) "PATH ordering is mutated when Codex shells launch via bash -lc" which fucks w nix, keep this in mind if you are ever trying to `cargo` something and you have a missing lib
118+
- A bug in codex exists that prevents you from finding the right path sometimes (https://github.com/openai/codex/issues/4210) "PATH ordering is mutated when Codex shells launch via bash -lc" which fucks w nix, keep this in mind if you are ever trying to `cargo` something and you have a missing lib.

0 commit comments

Comments
 (0)