xonecas.io
64875
Mc

mini-coder / commit d0a9f8e

docs: add dependency guidelines and lessons learned to AGENTS.md, relax tsconfig

xonecas2026-04-05 d0a9f8eecc2b53136ebc11def3360b06a7b29c64 parent 6837f35

2 files changed

AGENTS.md+16−0
@@ -28,6 +28,22 @@
2828 - Keep it minimal — don't add abstractions for hypothetical futures.
2929 - Performance matters. Prefer fast paths.
3030
31+## Working with dependencies
32+
33+- **Study before using.** Before writing code against a dependency, read its examples, types, and tsconfig. Match the dependency's conventions — don't fight them.
34+- **Match tsconfig constraints.** If a dependency ships `.ts` source (e.g., cel-tui), our tsconfig must be compatible with theirs. Relax our config to match, not the other way around. Never add lint-ignore comments or type casts to work around mismatched strictness settings.
35+- **Follow established patterns.** Dependencies with examples (e.g., `cel-tui/examples/chat.ts`) define the canonical usage patterns. Copy those patterns exactly before customizing. Don't invent alternative approaches.
36+- **Verify visual correctness.** For UI code, think through rendering on both light and dark terminals. Test color choices against both backgrounds. The spec says "adapts to the user's terminal color scheme" — that means colors must be legible in both contexts.
37+- **Understand layout before rendering.** For TUI frameworks, understand how the layout engine determines dimensions (intrinsic vs fixed vs flex vs fill). Never hardcode dimensions that the framework should compute.
38+
39+## Lessons learned
40+
41+- **Never rush an implementation.** A broken implementation that compiles is worse than no implementation — it wastes review time, erodes trust, and the rework costs more than doing it right the first time.
42+- **Don't suppress lint warnings for future code.** If code doesn't exist yet, don't add `biome-ignore` or `// @ts-ignore` comments for it. Add them when the code actually exists.
43+- **Dead guards are lies.** Type guards for impossible types (e.g., `typeof c !== "string"` when the type is `TextContent | ThinkingContent | ToolCall`) suggest the type can contain those values. They mislead readers and should not exist.
44+- **Event APIs must carry their data.** When an event handler needs data from the event source (e.g., tool call arguments), the event must carry that data. Walking external state to reconstruct it is fragile and breaks with duplicate entries.
45+- **Async callbacks must handle errors.** When a sync callback invokes an async function, the returned promise must be caught. Dropping it silently turns errors into unhandled rejections.
46+
3147 ## Testing strategy
3248
3349 We test our logic at the boundaries. Never test dependencies (pi-ai, cel-tui, bun:sqlite). Never use mocks or stubs.
tsconfig.json+0−2
@@ -6,8 +6,6 @@
66 "lib": ["ESNext"],
77 "types": ["bun"],
88 "strict": true,
9- "noUncheckedIndexedAccess": true,
10- "exactOptionalPropertyTypes": true,
119 "noImplicitReturns": true,
1210 "noFallthroughCasesInSwitch": true,
1311 "forceConsistentCasingInFileNames": true,