boring-engineering

Build exactly what the current problem requires. No less, no more.

An AI agent skill that turns KISS, YAGNI, and practical DRY into a concrete decision system — so your coding agent stops overengineering by default.

The Problem

AI agents already know what KISS, YAGNI, and DRY mean. What they consistently fail at is knowing when to apply them.

Left alone, agents tend to:

• Add abstractions before there's a second use case
• Build plugin systems for features with one consumer
• Create BaseServiceFactory for a function that needs 10 lines
• Future-proof code for requirements that never arrive

boring-engineering fixes this by giving the agent a concrete 4-step decision system it runs before and during every implementation — not just a reminder to "keep it simple."

How It Works

The skill loads in three stages (Agent Skills progressive disclosure):

Stage 1 — Discovery (~100 tokens)
At startup, the agent reads only the name and description from SKILL.md frontmatter. This is how it knows the skill exists without loading the full content.

Stage 2 — Activation
When you ask the agent to implement, refactor, or review code, it recognises the task matches this skill and loads the full SKILL.md body into context.

Stage 3 — Deep Reference (on demand)
If the agent needs to reason through a complex decision, it loads references/decision-framework.md or assets/decision-tree.md — only when the instructions point to them. These files never inflate context unnecessarily.

The 4-Step Decision System

Every time the agent writes or modifies code, it runs through:

Step 1 — Requirement Filter (YAGNI)
  Is this explicitly required? → NO: don't build it. YES: continue.

Step 2 — Reuse Check
  Does something already exist? → YES: reuse it. NO: continue.

Step 3 — Simplicity Check (KISS)
  What is the simplest correct solution? → Implement that.

Step 4 — Abstraction Check (Practical DRY)
  Is a new abstraction justified by proven repetition? → NO: keep it direct.

Full decision tree: assets/decision-tree.md
Deep reasoning: references/decision-framework.md

Setup

Option 1 — Clone the repo

git clone https://github.com/alvindemesadev/boring-engineering.git

Then copy the skill into your agent's skills directory (see per-tool instructions below).

Option 2 — Copy just the SKILL.md

If you only want the core skill without the reference files:

curl -O https://raw.githubusercontent.com/alvindemesadev/boring-engineering/main/SKILL.md

Compatibility

This skill uses the Agent Skills open spec — a standard supported by 40+ tools as of 2026. One SKILL.md, any compatible agent.

Consult your specific tool's documentation to confirm the exact path — most follow the .toolname/skills/ convention but some vary.

Install into your agent

Claude Code

mkdir -p .claude/skills/boring-engineering
cp /path/to/boring-engineering/SKILL.md .claude/skills/boring-engineering/SKILL.md

# Optional: copy reference files for on-demand loading
cp -r /path/to/boring-engineering/references .claude/skills/boring-engineering/
cp -r /path/to/boring-engineering/assets .claude/skills/boring-engineering/

Kiro

mkdir -p .kiro/skills/boring-engineering
cp /path/to/boring-engineering/SKILL.md .kiro/skills/boring-engineering/SKILL.md

# Optional: reference files
cp -r /path/to/boring-engineering/references .kiro/skills/boring-engineering/
cp -r /path/to/boring-engineering/assets .kiro/skills/boring-engineering/

Cursor

mkdir -p .cursor/skills/boring-engineering
cp /path/to/boring-engineering/SKILL.md .cursor/skills/boring-engineering/SKILL.md

OpenAI Codex

mkdir -p .codex/skills/boring-engineering
cp /path/to/boring-engineering/SKILL.md .codex/skills/boring-engineering/SKILL.md

Gemini CLI

mkdir -p .gemini/skills/boring-engineering
cp /path/to/boring-engineering/SKILL.md .gemini/skills/boring-engineering/SKILL.md

OpenCode

mkdir -p .opencode/skills/boring-engineering
cp /path/to/boring-engineering/SKILL.md .opencode/skills/boring-engineering/SKILL.md

Any other Agent Skills-compatible tool

mkdir -p .<toolname>/skills/boring-engineering
cp /path/to/boring-engineering/SKILL.md .<toolname>/skills/boring-engineering/SKILL.md

How to Use

Once installed, the skill activates automatically — no slash command or explicit invocation needed.

It activates when you:

It stays silent when you:

• Ask about deployment or CI/CD
• Debug a runtime error unrelated to code structure
• Configure infrastructure

What the agent does differently

Without the skill — agent receives: "Add a notification system"

Creates:
- NotificationService (abstract)
- EmailNotificationProvider
- PushNotificationProvider
- NotificationFactory
- NotificationRegistry
- INotificationStrategy (interface)

With the skill — agent runs the 4-step filter:

1. What's required? → Send an email notification on signup
2. Anything reusable? → No existing notification code
3. Simplest correct solution? → One function, one transport
4. Abstraction needed? → One use case, no proven repetition → keep direct

// notifications.js
export async function sendSignupEmail(user) {
  await mailer.send({
    to: user.email,
    subject: 'Welcome',
    html: welcomeTemplate(user),
  });
}

Example

More before/after comparisons:

• examples/bad-abstractions.md — patterns to avoid
• examples/good-abstractions.md — patterns to follow
• examples/before-after.md — real refactoring comparisons

Repo Structure

boring-engineering/
├── SKILL.md                          # The skill — this is what you install
├── README.md
├── LICENSE
│
├── assets/
│   └── decision-tree.md              # Full decision flow in one view (loaded on demand)
│
├── references/
│   ├── decision-framework.md         # Deep reasoning for each decision step
│   ├── kiss.md                       # KISS principle + decision rules
│   ├── yagni.md                      # YAGNI principle + decision rules
│   └── dry.md                        # Practical DRY + when NOT to abstract
│
└── examples/
    ├── bad-abstractions.md           # Patterns to avoid
    ├── good-abstractions.md          # Patterns to follow
    └── before-after.md              # Real refactoring comparisons

Principles

KISS — Keep It Simple

Prefer the simplest solution that is clear, maintainable, and correct. No unnecessary layers, patterns, or indirection. → references/kiss.md

YAGNI — You Aren't Gonna Need It

Implement only what is required now. No configuration options, extension points, or abstractions for hypothetical futures. → references/yagni.md

Practical DRY — Don't Repeat Yourself

Avoid meaningful duplication — but prefer duplication over a premature abstraction. Abstract only when the same logic exists in multiple real places and would need the same change. → references/dry.md

Benchmark — v1.1 (12 tickets × 5 arms × 5 tries) — fresh unbiased GO, 300/300

Honest 2-tier design inspired by ponytail's agentic benchmark — not a copy, same rigor (real file to reuse, 5 arms, fresh sandbox per cell, n=5). This is the unbiased 300-cell re-run on opencode-go/muse-spark-1.2-contributor (GO plan) — fully interleaved, no additive bias, no throttling.

Safety (6 tasks, 30 runs/arm, GO): boring 97% safe (29/30) vs ponytail 63% vs yagni 57% vs caveman 44% vs baseline 30% — the guards yagni/ponytail cut on auth-token/safe-path are the lines boring keeps. Full per-task tables, setup, and honest limitations → benchmarks/results/2026-08-28-boring-v1.1.md.

Tier A — agentic (git diff on real repo) is scaffolded in benchmarks/agentic/ and will replace this headline when it lands. Tier S is generation size; Tier A is diff size.

What This Skill Won't Remove

Simplicity is the default. These are always respected and never simplified away:

• Security and authentication
• Input validation and error handling
• Accessibility compliance
• Performance (with measured evidence)
• Reliability and fault tolerance
• Existing project architecture and conventions
• Explicit stakeholder requirements

License

MIT © Alvin de Mesa