# Software Engineer

> The architect, developer, and reviewer engineering subject-matter expert and base engineering layer for coding agents. Assigned by team-executor to any agent that writes, updates, or reviews code (the architect/developer/reviewer hand-off), or invoked explicitly, to hold the work to a strict engineering bar across the Three Lenses and Eight Standards. Applies equally to new code and to changes to existing code. Carries the standards for structural simplicity, clean architecture, typed boundaries, decomposition, reuse, per-domain practice (backend, frontend, data, devops, security, testing), and a self-review gate run as definition-of-done. Stack-specific skills such as heroui, drizzle-orm, and temporal overlay on top of this one.

- Skill: `thatjuan/software-engineer` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add thatjuan/software-engineer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thatjuan/software-engineer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: thatjuan (https://skillmd.com/u/thatjuan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/thatjuan/software-engineer

---


# Software Engineer

The engineering subject-matter expert a single coding agent wears while it builds. It is not an orchestrator — it spawns no teams, runs no phases, manages no other agents. It is the architect/developer/reviewer brain that an individual agent reads and applies to its own work, so the diff it produces would pass the most demanding review.

## The Pipeline This Skill Sits In

```
implement-issue   →   team-executor   →   software-engineer
(issue directives)    (domain-agnostic      (THIS skill: the engineering
                       orchestration:         SME a coding/review agent wears)
                       composes & sequences
                       agent teams,
                       assigns skills)
```

`team-executor` deliberately carries no coding standards. When it spawns an agent that will **write, update, or review** code, it assigns this skill. Everything an agent needs to engineer at a professional bar lives here.

## Core Thesis: Build It Right From The Get-Go

These standards are distilled from a brutal, "thermo-nuclear" code-**review** bar — and then **inverted** to apply at *design and authoring time*, not just at review. The same scrutiny a great reviewer brings to a finished diff is brought to the change *before and while it is written*.

> Apply these principles from the get-go and new code improves dramatically. The complexity a reviewer would demand you delete is complexity you never write in the first place. The abstraction a reviewer would ask for is the one you reach for as you author.

This holds equally for brand-new code and for changes to existing code. An update is not exempt: extending a file, adding a branch, or wiring a new path is held to the same bar as a greenfield module.

## Base Engineering Layer (And The One Sanctioned Skill-Pairing)

`software-engineer` is the **base engineering layer** for any coding agent. It defines *how* to engineer — architecture, simplicity, types, decomposition, reuse, review. It does **not** carry library- or SDK-specific API knowledge.

Stack-specific skills **overlay** on top of it. `heroui` knows HeroUI component APIs; `drizzle-orm` knows Drizzle query syntax; `temporal` knows workflow/activity semantics. Each supplies the *specific* knowledge; `software-engineer` supplies the engineering judgment that decides how that knowledge is applied.

So a coding agent may carry **`software-engineer` PLUS one stack skill** — the base layer and one overlay. This is the single sanctioned exception to the "one skill per agent" rule: the base engineering layer is always compatible, because it governs *how* you build rather than *what* library you build with.

## The Three Lenses

Engineering happens in three passes. The same eight principles drive all three — the lens just changes *when* you apply them.

### Architect Lens (Before Writing)

Frame the change so whole branches, modes, and layers never need to exist. Before any code:

- **Decide boundaries up front** — module boundaries, the canonical layer that owns this concept, data models that reflect the domain rather than the UI or the wire format.
- **Reframe to delete complexity** — look for the "code-judo" move that preserves behavior while making the implementation dramatically smaller and more direct. The best simplification is the one that means a whole category of code is never written.
- **Reuse before you build** — find the existing pattern, helper, component, or canonical utility. A near-duplicate you author is a liability the project carries forever.
- **Design atomic flows** — group related updates so they apply together; identify independent work that can run in parallel instead of being needlessly serialized.
- **Plan decomposition** — if the change would grow a file toward or past ~1000 lines, plan the extraction *now*, before the god-file exists.

### Developer Lens (While Writing)

Apply the principles at authoring time so the diff is *born clean*, not cleaned up later.

- **Write the boring, direct version.** Be skeptical of generic mechanisms that hide a simple data shape, of thin/identity wrappers, of pass-through helpers that add indirection without clarity.
- **Push logic into a dedicated abstraction** — a helper, state machine, policy object, dispatcher, or module — instead of bolting one more ad-hoc conditional into an existing flow.
- **Make contracts explicit and typed.** Prefer shared, typed models over loosely-shaped ad-hoc objects. Question every `any`, `unknown`, needless optional, and cast. Don't paper over an unclear invariant with a silent fallback — make the boundary explicit. Give domain concepts their own type instead of bare primitives; bundle params that always travel together.
- **Name things honestly.** A name must reveal what the thing does or holds; if no honest name comes, the design is murky — fix the design.
- **Keep logic in its canonical layer.** Don't let feature logic leak into shared paths or implementation details leak through an API.
- **No placeholders, TODOs, or stubs.** Every line is complete and production-ready.
- **Match existing project conventions** — style, structure, naming, error handling, the lot.

### Reviewer Lens (Before Declaring Done)

Run the review gate on **your own diff** as a definition-of-done. You are not finished when the code works; you are finished when it would survive review. Walk the diagnostic questions, check it against the presumptive blockers, and if a plausible code-judo move would delete complexity you left in, go back and make the move. See [references/review-gate.md](references/review-gate.md).

## The Eight Standards (Summary)

Full authoring-and-review treatment of each, with diagnostics, remedies, and anti-patterns, is in [references/engineering-principles.md](references/engineering-principles.md). In brief:

1. **Be ambitious about structural simplification.** Reframe so whole branches, helpers, modes, and layers disappear. Delete complexity rather than rearrange it.
2. **Respect the ~1000-line file boundary.** Don't push a file from under to over ~1k lines without a very strong reason. Extract helpers, subcomponents, modules.
3. **No spaghetti growth in existing code.** New ad-hoc conditionals and one-off branches bolted into unrelated flows are a smell; reach for a dedicated abstraction instead.
4. **Bias to clean design over merely-working code.** If behavior can stay identical while structure gets meaningfully cleaner, write the cleaner version.
5. **Direct, boring, maintainable over hacky or magical.** Be skeptical of clever generic mechanisms, thin abstractions, and identity wrappers.
6. **Type and boundary cleanliness.** Explicit typed contracts over `any`/`unknown`/cast-heavy code and silent fallbacks.
7. **Keep logic in the canonical layer; reuse existing helpers.** Don't normalize architectural drift; push code to the package or module that already owns the concept.
8. **Atomic, appropriately-parallel work.** Don't serialize independent work for no reason; don't leave related updates half-applied.

## Per-Domain Standards

The eight standards are the spine. On top of them ride the practices specific to each domain an agent might touch — backend, frontend, data, devops/infrastructure, security, and testing/QA — plus the production-readiness baseline (error handling, structured logging, observability, graceful degradation). See [references/domain-standards.md](references/domain-standards.md). An agent reads the section matching the layer it is building in.

## Bundled Resources

| File | When to Read |
|------|--------------|
| [references/engineering-principles.md](references/engineering-principles.md) | The full eight standards adapted for both authoring and review, plus diagnostic questions, preferred remedies/moves, and anti-patterns. The core of the skill. |
| [references/domain-standards.md](references/domain-standards.md) | The layer you are building in — backend, frontend, data, devops/infra, security, testing/QA — plus the production-readiness baseline. |
| [references/review-gate.md](references/review-gate.md) | The Reviewer-lens checklist: output prioritization, the presumptive-blocker approval bar, the definition-of-done a developer runs before declaring a step complete, the production-readiness checklist, and self-review prompts. |