The operating system for AI-assisted software engineering in TypeScript, React, and Next.js.

elite-engineer is a portable ruleset for tools like Cursor, Claude Code, Claude.ai, and any assistant that supports custom instructions or system prompts.

It is designed to push models away from default AI output:

• boolean state machines instead of impossible-state-proof unions
• useEffect used as an event system
• shallow folder structures and pass-through layers
• unsafe TypeScript with any, as, and runtime trust
• visually flat, generic UI with weak hierarchy and no motion discipline

and toward code that is:

• typed honestly
• architected in vertical slices
• grounded in named sources
• visually deliberate
• performance-aware
• reviewable by strong engineers without immediate cleanup

Fastest install:

1. Download elite-engineer-codex-skill.zip from the latest Releases.
2. Extract the elite-engineer folder into ~/.codex/skills/.
3. Restart Codex.
4. Use it explicitly:

Use $elite-engineer to build this feature.

If you have this repo cloned locally, you can also install directly:

./scripts/install-codex-skill.ps1

./scripts/install-codex-skill.sh

Full Codex guide: docs/codex.md

This repository is not an app, library, or framework. It is a skill/instruction system you attach to an AI coding tool so the model generates better code and makes better engineering decisions.

The standard is intentionally opinionated. It does not try to represent every valid style. It encodes a specific point of view:

• Linus Torvalds on taste and removing special cases
• John Ousterhout on deep modules and complexity management
• Dan Abramov on effects as synchronization
• Rich Hickey on simple vs easy
• Fred Brooks on essential complexity
• Sandi Metz and Kent C. Dodds on resisting premature abstraction
• Tanner Linsley on server state
• Eric Evans and Jimmy Bogard on domain boundaries and vertical slices

If you want AI output that feels closer to Linear, Stripe, Vercel, Radix, or a disciplined product engineering team, this repo is aimed at that use case.

elite-engineer changes both what the model writes and how it thinks before writing.

• models essential complexity before coding
• prefers deep modules over shallow wrappers
• treats architecture as a first-class concern
• defaults to vertical slices over horizontal layers
• avoids accidental complexity and weak abstractions

• uses branded types at identity boundaries
• uses discriminated unions for async and UI state
• parses with Zod at boundaries instead of trusting input
• uses as const satisfies for strong inference
• treats any, as, !, and @ts-ignore as last-resort smells

• uses useEffect only for external synchronization
• distinguishes server state from client state
• defaults to Server Components and pushes 'use client' to leaves
• encourages deep custom hooks and colocated feature logic
• uses optimistic updates, Suspense, and proper async boundaries

• applies a real type scale
• uses OKLCH and semantic tokens
• respects spacing systems and motion roles
• avoids generic "AI slop" interfaces
• favors design systems that can scale

• recognizes common AI anti-patterns immediately
• recommends specific replacements, not vague style advice
• pushes toward code that is easier to maintain six months later

The repo includes concrete before/after examples showing the kind of transformation this standard is meant to produce.

const [isLoading, setIsLoading] = useState(false);
const [isError, setIsError] = useState(false);
const [data, setData] = useState(null);

useEffect(() => {
  setIsLoading(true);
  fetch(`/api/users/${userId}`)
    .then((res) => res.json())
    .then((value) => {
      setData(value);
      setIsLoading(false);
    })
    .catch(() => {
      setIsError(true);
      setIsLoading(false);
    });
}, [userId]);

const UserSchema = z.object({
  id: z.string().transform(UserId),
  name: z.string(),
  email: z.string().email(),
});

type User = z.infer<typeof UserSchema>;

function userOptions(id: UserId) {
  return queryOptions({
    queryKey: ['users', id] as const,
    queryFn: async () => {
      const res = await fetch(`/api/users/${id}`);
      if (!res.ok) throw new Error(`Failed to fetch user ${id}`);
      return UserSchema.parse(await res.json());
    },
  });
}

const { data: user } = useSuspenseQuery(userOptions(userId));

More examples:

• examples/before-after-data-fetching.tsx
• examples/before-after-typescript.tsx
• examples/before-after-components.tsx

This repo contains the same standard in a few different packaging formats.

If you only read one file, read SKILL.md.

Pick the integration that matches your AI tool. You usually need one entrypoint, not all of them.

Copy .cursorrules into the root of the project where you want the rules applied.

cp /path/to/elite-engineer/.cursorrules /path/to/your-project/.cursorrules

Copy .claude/CLAUDE.md into the target project's .claude/ directory.

mkdir -p /path/to/your-project/.claude
cp /path/to/elite-engineer/.claude/CLAUDE.md /path/to/your-project/.claude/CLAUDE.md

Use the packaged elite-engineer.skill file through Claude.ai's skill flow.

Use the packaged Codex skill folder at codex-skill/elite-engineer.

There are two install paths:

• download elite-engineer-codex-skill.zip from Releases and extract it into ~/.codex/skills/
• install directly from the repo path codex-skill/elite-engineer with Codex's skill installer
• run a local installer script from this repo if you already cloned it

Full tutorial: docs/codex.md

Paste the contents of SKILL.md into the tool's system prompt, custom instructions, or shared project instructions.

If multiple engineers are using the same AI stack, keep the repo as a shared reference and standardize on one of these entrypoints:

• .cursorrules for Cursor teams
• .claude/CLAUDE.md for Claude Code projects
• SKILL.md for platform-agnostic internal prompts

Installing the rules is only part of the value. The better results come from pairing the skill with the right task framing.

• generate a new feature in TypeScript / React / Next.js
• refactor a legacy component into a clearer architecture
• review a pull request for AI anti-patterns
• create design-system primitives and variants
• improve perceived performance and loading states
• model a domain before writing UI

Ask the model to do the task and to follow the standard explicitly.

Example prompts:

Build this dashboard using the elite-engineer standard. Use vertical slices, Zod at boundaries, TanStack Query for server state, and avoid useEffect for derived state.

Refactor this component using elite-engineer rules. Split out deep hooks, replace boolean async state with a discriminated union, and push client-only logic to leaf components.

Review this diff against the elite-engineer anti-pattern blacklist and call out anything that would not survive a strong team review.

Have the model read the relevant reference file before it starts coding.

For bigger tasks, start with architecture and then pull in the domain-specific references.

.
|-- .claude/
|   `-- CLAUDE.md
|-- codex-skill/
|   `-- elite-engineer/
|       |-- SKILL.md
|       |-- agents/
|       |   `-- openai.yaml
|       `-- references/
|-- docs/
|   `-- codex.md
|-- examples/
|   |-- before-after-components.tsx
|   |-- before-after-data-fetching.tsx
|   `-- before-after-typescript.tsx
|-- references/
|   |-- anti-patterns.md
|   |-- architecture.md
|   |-- design-system.md
|   |-- react-nextjs-patterns.md
|   |-- typescript-patterns.md
|   `-- visual-standard.md
|-- .cursorrules
|-- CONTRIBUTING.md
|-- elite-engineer.skill
|-- LICENSE
|-- README.md
|-- scripts/
|   |-- build-codex-skill.ps1
|   |-- install-codex-skill.ps1
|   `-- install-codex-skill.sh
`-- SKILL.md

• SKILL.md is the primary readable version of the standard.
• codex-skill/elite-engineer is the Codex-installable distribution of the skill.
• references/*.md contain the deeper explanations, examples, and decision trees.
• .cursorrules and .claude/CLAUDE.md are delivery formats for specific tools.
• elite-engineer.skill is the packaged artifact for Claude.ai.
• docs/codex.md explains how to install and use the Codex version.
• scripts/build-codex-skill.ps1 produces the zip artifact for GitHub Releases.
• scripts/install-codex-skill.ps1 and scripts/install-codex-skill.sh install the Codex skill from a local clone.
• examples/*.tsx show what changes in practice.

At a high level, the skill is organized around a few major pillars.

Seek the formulation where special cases disappear. Favor representations that make misuse difficult and correctness natural.

Before coding, clarify:

• what complexity is essential
• where the boundaries are
• what the pit of success looks like
• whether the solution is simple, not just easy
• whether abstraction has actually been earned

• deep modules over shallow wrappers
• vertical slices over horizontal technical layers
• inward-pointing dependencies
• explicit server/client boundaries
• fewer pass-through abstractions

• branded types for identity safety
• discriminated unions for impossible states
• Zod at all external data boundaries
• strong inference instead of annotation theater
• no fake safety via unchecked casts

• effects for synchronization only
• clear distinction between server state and local UI state
• Server Components by default
• deep hooks that hide complexity behind small interfaces
• optimistic updates and Suspense-aware async flows

• naming that reads like prose
• guard clauses and flattened control flow
• table-driven logic where condition chains are brittle
• short functions with bounded complexity
• comments that explain why, not what

• modular type scales
• OKLCH and semantic color systems
• spacing systems with real hierarchy
• purposeful animation
• stronger defaults for product UI

The repo names common AI failures directly and gives exact replacements, including:

• useEffect as event handler
• state synchronization traps
• loading booleans
• premature abstraction
• type theater
• mega-components
• dependency-array suppression

The project separates portable instructions from deep references.

That split matters because most tools want a concise rules file, while real engineering work often needs deeper explanation and examples.

• The rules files are what you install into the assistant.
• The reference files are what the assistant should consult before larger tasks.
• The examples make the expected output concrete instead of rhetorical.

This keeps the installation artifacts small enough to use, without flattening the entire engineering standard into a vague checklist.

This repository is intentionally source-grounded. It is not a collection of floating "best practices."

Named sources include:

• Linus Torvalds
• John Ousterhout
• Dan Abramov
• Rich Hickey
• John Carmack
• Fred Brooks
• Sandi Metz
• Kent C. Dodds
• Tanner Linsley
• Eric Evans
• Jimmy Bogard
• Brad Abrams
• Rico Mariani

Production codebases and systems studied include:

• Linear
• Stripe
• Vercel
• Radix UI
• tRPC
• Zod
• TanStack Query
• GitHub Primer
• Adobe Spectrum
• Radix Colors

The goal is not to imitate any single company. The goal is to distill recurring patterns from teams and engineers with unusually high standards.

Contributions are welcome, but the bar is intentional.

Every addition should satisfy all three:

1. It traces to a named source.
2. It is actionable enough to change the model's output.
3. If it identifies an anti-pattern, it also provides the replacement.

See CONTRIBUTING.md for the full rules.

Useful contribution areas:

• stronger before/after examples
• better source citations
• new anti-patterns with concrete fixes
• clearer decision trees
• stack adaptations for ecosystems beyond TypeScript / React / Next.js

No. It is written for AI-assisted workflows, but it is also a readable engineering standard for humans. The references and examples stand on their own.

The center of gravity is TypeScript, React, Next.js, and product UI. Some principles are general software design guidance, but the examples and rules are strongest in those domains.

No. It raises the floor and makes better default decisions more likely. Strong engineering still requires context, tradeoff analysis, and judgment.

Yes, sometimes. That is part of the point. A useful standard needs sharp edges. Teams can fork or adapt it to match their own taste and stack.

If this repo materially improves the quality of your AI-assisted coding workflow, star it so other engineers can find it.

MIT. Use it, adapt it, fork it, and share it with your team.