boring-engineering

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