agent-skills: Instructions file for Codex

AGENTS.md

Battle-tested engineering judgment for code, refactors, tests, and frontend UI. Merge with project-specific instructions as needed.

Tradeoff: These guidelines bias toward caution over speed. Ultra-terse output style applies during code work. For trivial tasks, use judgment.

Goal: least code, fix problem, no break working stuff.

Output style

Output style

• Explain in simple terms like a human.
• Write specs as if any engineer would easily catch. Every spec/adr/decision doc/explanation/answer should be simple, easy to understand for human engineers with no over-complication, no unnecessary details, no repeated redundant explanation in multiple blocks.
• Document core business workflows, decisions, algorithms, approaches.
• No extra explanation than asked.
• No decorative tables, emoji, tool narration. Errors: quote shortest relevant line only.

1. Think before code

• State assumption, no guess.
• Multi interpretation → show all, no pick.
• Unclear ask → stop, name confusion, ask.
• Simpler way exist → say it.

2. Simplicity

• Senior-line estimate; actual >4x → cut.
• No unrequested feature/flexibility/config/error-handling for impossible case.
• Prefer stdlib/dep over hand-roll.
• Function many unrelated thing → split single-responsibility. Already one thing → leave.
• YAGNI/DRY/SOLID when shape need — not checklist.
• Comment why, not what.
• Red flag: single-use abstraction, one-method "manager", options object one caller.

3. Architecture boundaries (Clean Architecture)

• Business rules are the center. Code depends inward, never outward.
• Frameworks are tools, not foundations. UI, ORM, web framework, database are replaceable details.
• Controllers thin: translate input/output only. No business decisions.
• Use cases focused: one use case = one application action.
• Domain models clean: no database, HTTP, framework, or infrastructure knowledge inside.
• Business behavior near business data. Do not scatter rules across controllers/services/helpers.
• Interfaces at real boundaries: external systems, storage, APIs, queues. No fake abstraction.
• Dependencies explicit. Avoid hidden globals, magic imports, service locators, or implicit coupling.
• Composition over inheritance. Assemble behavior instead of deep class trees.
• Organize around business capabilities, not technical layers.

Bad:    controllers/ services/ repositories/
Better: orders/ payments/ users/

• Design for change. Protect stable business rules from changing technology.
• Dependency direction matters more than folder structure.
• If removing a framework requires rewriting business logic, the boundary is wrong.