AGENTS.md - Engineering Operating System (saving tokens)

AGENTS.md

AGENTS.md - Engineering Operating System

Project Context

Stack

• Tech Stack: [Node.js 22 or higher, TypeScript 5.x, Next.js 15, Tailwind]
• Architecture: [Clean Architecture / Modular Monolith]
• Environment: Production

---

Primary Objective

Implement the requested change with:

1. Minimum code changes
2. Maximum correctness
3. Maximum reuse of existing code
4. Minimum token consumption
5. Zero architectural degradation

---

Decision Hierarchy

When tradeoffs exist, follow this order:

1. Correctness
2. Existing Architecture
3. Existing Conventions
4. Simplicity
5. Token Efficiency
6. New Abstractions

Never sacrifice higher priorities for lower ones.

---

Change Strategy

Before writing code:

1. Identify the exact files that require modification.
2. Trace the execution flow affected by the request.
3. Determine the smallest possible implementation.
4. Reuse existing services, utilities, hooks, repositories, and components whenever possible.
5. Do not introduce abstractions unless duplication already exists or is clearly imminent.

---

Token Efficiency Rules

Required

• Modify only files directly involved in the request.
• Show only changed sections whenever possible.
• Preserve untouched code.
• Avoid repeating existing code for context.
• Avoid verbose explanations.

Forbidden

• Rewriting entire files unnecessarily.
• Reformatting unrelated code.
• Renaming symbols without necessity.
• Moving files without necessity.
• Generating large code blocks for small changes.

---

Architecture Protection Rules

Forbidden

• Bypassing service layers.
• Bypassing repositories.
• Duplicating business logic.
• Introducing hidden side effects.
• Mixing infrastructure concerns with domain logic.

Required

• Respect existing architectural boundaries.
• Keep dependency direction unchanged.
• Maintain separation of concerns.

---

TypeScript Standards

Required

• Strict typing.
• No implicit any.
• Explicit return types for public APIs.
• Exhaustive handling of discriminated unions.
• Proper null/undefined handling.

Forbidden

• any
• @ts-ignore
• @ts-expect-error without justification
• Unsafe type assertions

---

Dependency Rules

Before adding a dependency:

1. Verify the feature cannot be implemented with existing dependencies.
2. Verify the runtime benefit outweighs maintenance cost.
3. Prefer platform-native APIs.

Never introduce a package that duplicates existing functionality.

---

Testing Policy

If test infrastructure exists:

1. Run impacted tests.
2. Run type checking.
3. Run linting when available.

Suggested order:

npm run test
npm run typecheck
npm run lint

If failures occur:

1. Analyze root cause.
2. Fix code.
3. Re-run validations.

Never modify tests merely to make failures disappear unless the request explicitly requires updating test behavior.

---

Definition of Done

A task is complete only when:

• Requested behavior is implemented.
• Existing behavior remains unchanged.
• Type checks pass.
• Relevant tests pass.
• No architectural rules were violated.
• No dead code remains.
• No unnecessary dependencies were introduced.

---

Output Rules

Unless explicitly requested otherwise:

• Return only the necessary code changes.
• Do not provide tutorials.
• Do not explain obvious code.
• Do not generate implementation alternatives.
• Do not include marketing-style commentary.

Be concise, precise, and implementation-focused.