# Agent Behavior Guidelines — ByteLyst Ecosystem > **Single source of truth.** This file is the canonical agent behavior contract > for every repo in the ByteLyst workspace. Every per-repo `AGENTS.md` points > here. Do not duplicate these rules into per-repo agent files. > > **Location:** `learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md` > From any sibling repo: `../learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md` These rules apply to every AI coding agent (Claude Code, Cursor, Windsurf Cascade, GitHub Copilot, OpenAI Codex, Cline, Aider, etc.) working in any ByteLyst repo. --- ## Part A — Universal Behavior (adapted from Karpathy's CLAUDE.md) Source attribution: behavioral guidelines below adapted from . These bias toward caution over speed. For trivial tasks, use judgment. ### A1. Think Before Coding **Don't assume. Don't hide confusion. Surface tradeoffs.** Before implementing: - State your assumptions explicitly. If uncertain, ask. - If multiple interpretations exist, present them — don't pick silently. - If a simpler approach exists, say so. Push back when warranted. - If something is unclear, stop. Name what's confusing. Ask. ### A2. Simplicity First **Minimum code that solves the problem. Nothing speculative.** - No features beyond what was asked. - No abstractions for single-use code. - No "flexibility" or "configurability" that wasn't requested. - No error handling for impossible scenarios. - If you write 200 lines and it could be 50, rewrite it. Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. ### A3. Surgical Changes **Touch only what you must. Clean up only your own mess.** When editing existing code: - Don't "improve" adjacent code, comments, or formatting. - Don't refactor things that aren't broken. - Match existing style, even if you'd do it differently. - If you notice unrelated dead code, mention it — don't delete it. When your changes create orphans: - Remove imports/variables/functions that **your** changes made unused. - Don't remove pre-existing dead code unless asked. **The test:** Every changed line should trace directly to the user's request. ### A4. Goal-Driven Execution **Define success criteria. Loop until verified.** Transform tasks into verifiable goals: - "Add validation" → "Write tests for invalid inputs, then make them pass" - "Fix the bug" → "Write a test that reproduces it, then make it pass" - "Refactor X" → "Ensure tests pass before and after" For multi-step tasks, state a brief plan: ```text 1. [Step] → verify: [check] 2. [Step] → verify: [check] 3. [Step] → verify: [check] ``` Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. --- ## Part B — ByteLyst Ecosystem Rules These extend Part A with ecosystem-specific discipline. They apply to every repo. ### B1. Tests are sacred - **Never modify tests to make them pass.** Fix the source code, or stop and ask. - **Never delete or weaken tests** without explicit user direction. - When fixing a bug, add a regression test first. ### B2. Verify before claiming done - Run the repo's documented `Build Verification` block (see each AGENTS.md § "Build Verification") before reporting completion. - If you cannot run verification, say so explicitly — don't claim "should work". - For multi-repo changes, verify each affected repo. ### B3. Never edit shared infrastructure casually - `.npmrc` is managed by `learning_ai_common_plat/scripts/npmrc.template`. Never hand-edit. Use `bash scripts/sync-npmrc.sh`. - `@bytelyst/*` packages live in `learning_ai_common_plat/packages/`. Changes ripple across all products — flag cross-repo impact before editing. - Agent docs (`AGENTS.md`, `.github/copilot-instructions.md`, etc.) are managed by `learning_ai_common_plat/scripts/update-agent-docs.sh`. Never hand-edit generated files. Edit the template or per-repo metadata instead. ### B4. Logging and secrets - Never use `console.log` in production code — use `req.log` / `app.log` (Fastify), `structlog` (Python), `os.Logger` (Swift). - Never use `print()` in Swift. - Never hardcode secrets, API keys, OAuth client IDs, or URLs. Use env vars or Azure Key Vault. ### B5. Cosmos discipline - Every Cosmos document MUST include a `productId` field. - Use `PRODUCT_ID` from `@bytelyst/config` (or `shared/product.json`) — never hardcode product IDs as string literals. ### B6. Commit hygiene - Format: `type(scope): description` - Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore` - Keep commits atomic. One logical change per commit. - Run pre-commit hooks. Do not bypass with `--no-verify` unless asked. ### B7. Style preservation - Never delete existing comments or documentation unless explicitly asked. - Never add emojis unless explicitly asked. - Match the existing code style of the file you're editing. --- ## Part C — Tool-Specific Notes All AI coding tools should read this file. The conventions for how each tool discovers it: - **Claude Code** — reads `AGENTS.md` (per-repo) which links here. - **Cursor** — reads `AGENTS.md` (per-repo) which links here. Multi-root workspace must include `learning_ai_common_plat` so the sibling path resolves. - **Windsurf / Cascade** — reads `AGENTS.md` (per-repo). Workspace must include `learning_ai_common_plat`. - **GitHub Copilot** — reads `.github/copilot-instructions.md` (per-repo) which points here. Copilot does not always follow cross-file references; the pointer file is a best-effort. - **OpenAI Codex** — reads `AGENTS.md` (per-repo). - **Cline / Roo Code** — reads `AGENTS.md` (per-repo) via its standard agent file discovery. - **Aider** — `.aider.conf.yml` (per-repo) declares `read: AGENTS.md` and `conventions: AGENTS.md`. If your tool does not appear here, default to reading `AGENTS.md` at the repo root. --- ## Maintenance - Edit this file in place. Changes take effect for every repo on next agent invocation — no regeneration needed (it is referenced, not copied). - After editing, run `bash scripts/check-agent-docs-drift.sh` from `learning_ai_common_plat` to confirm no per-repo file has drifted out of sync. - See `learning_ai_common_plat/.windsurf/workflows/repo_update-agent-docs.md` for the full propagation workflow.