docs(agents): standardize agent instruction symlinks#25
Conversation
Merge the diverged AGENTS.md and CLAUDE.md into a single source of truth at AGENTS.md, then replace CLAUDE.md with a git symlink (mode 120000) pointing to it. AGENTS.md now carries the union of both files (Compatibility Contract, mockEmbeddings, api-smoke publish gate, detailed Release Automation) plus a Windows-safe recipe for recreating the symlink.
Add a knowledge-track learning under docs/solutions/conventions/ that explains why AGENTS.md is the single source of truth, why CLAUDE.md is a git symlink (mode 120000), the Windows footguns to avoid (ln -s, cp, here-strings), and that the convention applies recursively to any subdirectory CLAUDE.md.
…S.md Cut Architecture from ~75 lines to a 15-line overview that points at docs/design/*, dropping the duplication that was paying a token tax on every agent turn. Backfill higher-leverage content: - Add a Don't/Gotchas section (matrix:live burns real quota, dist/ is build output, shouldUse* is legacy, translators must not silently drop fields, conventional commits, no --no-verify). - Add a four-step "Adding a New Route" recipe. - Promote scope-discipline into Code Conventions so it's not memory-only. - Reorder local validation to match CI (lint:all -> typecheck -> test -> build) so test failures surface before the bundle step. - Tighten the Bun runtime rule into an actionable boundary: Bun-native APIs in scripts/ and tests/, Web/Node standard APIs in src/. Extract test-runner conventions and the tests/helpers.ts inventory into tests/AGENTS.md. Add tests/CLAUDE.md as a git symlink (mode 120000) to tests/AGENTS.md so the same single-source convention works at nested scope. Root AGENTS.md drops from 220 to 162 lines (-26%).
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 99c54d7553
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - **Runtime:** Bun is first-class. Prefer Bun-native APIs unless cross-runtime support is explicitly needed. | ||
| - **Complexity:** Favor direct implementation over unnecessary abstractions. Three similar lines is better than a premature helper. | ||
| - **Scope discipline:** Fix only the issue the change targets. Don't refactor pre-existing duplication or "while you're there" — small, focused diffs review better and revert cleaner. | ||
| - **Runtime APIs:** Bun-native APIs (`Bun.file`, `Bun.serve`, `Bun.sleep`, etc.) are fine in `scripts/` and `tests/`. **Route code under `src/` must work on both Bun and Node** — use Web/Node standard APIs (`fetch`, `Response`, `crypto.subtle`, etc.). The CI smoke test runs the packaged CLI under Node via `@elysiajs/node`. |
There was a problem hiding this comment.
When a contributor adds a Bun-only API under src/, this sentence implies that CI will catch the Node incompatibility, but the packaged smoke path does not exercise Node: the build job runs bun run smoke:packaged in .github/workflows/ci.yml, and scripts/packaged-smoke-test.ts:130 launches ['bun', packagedBinPath, '--help']. It also checks CLI help only, so it never starts the @elysiajs/node adapter or executes route code. Keep the cross-runtime rule, but remove the claimed coverage or add an actual Node server smoke test.
Useful? React with 👍 / 👎.
1 participant
Summary
Agent instructions now have a single source of truth across Codex, Claude Code, and nested test guidance. The PR documents the symlink convention directly where future agents will read it, keeps test-specific guidance scoped under
tests/, and records the Windows-safe recovery path soCLAUDE.mdfiles do not silently drift into regular copies.Verification
bun run lint:allgit diff --checkgit ls-files -s CLAUDE.md tests/CLAUDE.mdconfirms both entries are mode120000git cat-file -p HEAD:CLAUDE.mdandgit cat-file -p HEAD:tests/CLAUDE.mdboth resolve toAGENTS.md