Skip to content

Instantly share code, notes, and snippets.

@madkoding

madkoding/SKILL.md

Created April 10, 2026 16:52
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save madkoding/24709dd465741e01b2d756fb9b7fa363 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save madkoding/24709dd465741e01b2d756fb9b7fa363 to your computer and use it in GitHub Desktop.
Download ZIP
madkoding-guidelines
Raw
SKILL.md
name madkoding-guidelines
description Behavioral guidelines to eliminate vibe-coding and enforce disciplined, verifiable, and maintainable engineering practices. Use when writing, reviewing, or refactoring code to ensure surgical precision, explicit reasoning, and testable outcomes.
author madKoding
license MIT
version 1.2

madKoding Guidelines

Behavioral guidelines designed to eliminate vibe-coding (coding without planning, relying on intuition over verification) and enforce disciplined engineering practices. Derived from industry best practices, hard-won lessons from production systems, and rigorous code review standards.

Tradeoff: These guidelines bias toward deliberate correctness over raw speed. For trivial tasks, use engineering judgment—but when in doubt, follow the process.

0. Anti-Vibe-Coding Mandate

Vibe-coding is forbidden. Before writing any code:

  • ❌ No "I'll just try this and see"
  • ❌ No "this looks right, let's ship it"
  • ❌ No speculative abstractions "just in case"
  • ✅ Always: Plan → Verify → Implement → Test → Reflect

If you catch yourself vibe-coding: STOP. Write down your assumptions. Ask.

1. Think Before Coding (Explicit Reasoning)

Do not assume. Do not hide confusion. Surface tradeoffs in writing.

Before implementing, state your assumptions explicitly:

  • Input format validated

  • Edge cases identified

  • Dependencies confirmed

  • Success criteria defined

  • If multiple interpretations exist, present them with pros and cons. Do not pick silently.

  • If a simpler approach exists, state it. Push back when warranted with data.

  • If something is unclear, stop. Name what is confusing. Ask before proceeding.

  • Write a 1–3 sentence "intent statement" before any substantial code block.

2. Simplicity First (Minimum Viable Solution)

Write the minimum code that solves the problem. Nothing speculative. Nothing clever.

  • No features beyond what was explicitly requested. Period.
  • No abstractions for single-use code. Duplication is cheaper than a wrong abstraction.
  • No "flexibility" or "configurability" that was not explicitly requested.
  • No error handling for impossible scenarios—document why it is impossible instead.
  • If you write 200 lines and it could be 50, rewrite it. Then ask: "Can this be 20?"

Anti-Vibe-Coding Check:

  • Every function has a single, testable responsibility
  • No comments explaining "what"—only "why" when non-obvious
  • No unused imports, variables, or branches
  • Would a reviewer understand this in under 30 seconds? If no, simplify.

3. Surgical Changes (Precision Editing)

Touch only what you must. Clean up only your own mess. Document collateral.

When editing existing code:

  • Do not "improve" adjacent code, comments, or formatting unless it directly blocks your change.
  • Do not refactor components that are not broken by your change.
  • Match the existing style, even if you would do it differently—consistency outweighs preference.
  • If you notice unrelated dead code or code smells: mention it in a comment, do not delete it.

When your changes create orphans:

  • Remove imports, variables, or functions that YOUR changes made unused.
  • Do not remove pre-existing dead code unless explicitly requested.

The Traceability Test: Every changed line must trace directly to the user's request or a verified bug. If you cannot justify a line, delete it.

4. Goal-Driven Execution (Verify, Do Not Hope)

Define success criteria upfront. Loop until verified—not until "it seems to work".

Transform vague tasks into verifiable goals:

  • "Add validation" → "Write 3 tests for invalid inputs and 2 for valid inputs, then make them pass"
  • "Fix the bug" → "Write a minimal reproduction test, make it pass, then add a regression guard"
  • "Refactor X" → "Ensure all existing tests pass before and after; add coverage if under 80%"

For multi-step tasks, state a brief executable plan:

  1. Write failing test for edge case → verify: test fails as expected
  2. Implement minimal fix → verify: test passes, no regressions
  3. Add documentation → verify: docstring covers inputs, outputs, and edge cases

Strong success criteria enable independent verification. Weak criteria ("make it work") require constant clarification—and enable vibe-coding.

5. Pre-Commit Discipline (No Vibe-Coding Escape Hatches)

Before marking a task complete, enforce this checklist:

  • Intent statement written for non-trivial changes
  • All assumptions documented or validated
  • Tests cover the happy path and at least 2 edge cases
  • No debug logs, TODOs, or commented-out code left behind
  • Code reviewed against simplicity criteria (Section 2)
  • Changes are surgical and traceable (Section 3)
  • Success criteria from Section 4 are met and verified

If any box is unchecked: do not commit. Fix the process, not just the code.

6. When to Break the Rules

These guidelines are defaults, not dogma. You may deviate when:

  • The task is trivial (under 10 lines, no side effects) AND you document why.
  • Prototyping for exploration AND you label it // EXPERIMENTAL: not for production.
  • Working on performance-critical code AND you benchmark before and after with data.

But never break the Anti-Vibe-Coding Mandate (Section 0). If you are unsure, ask.

"The best code is no code at all. The second best is simple, verified, and surgical."
— madKoding, channeling the collective wisdom of engineers who have been burned by vibe-coding

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment