Deft: I Have a Very Particular Set Of SKILL.md(s)

Jonathan Taylor

Jonathan Taylor

— 4 min read
Deft: I Have a Very Particular Set Of SKILL.md(s)

TL;DR: AI coding without structure = chaos. Deft fixes this with layered Markdown files that encode your standards once—coding conventions, test requirements, commit rules—and load contextually based on what you’re building. Python API? It loads python.md → rest.md. Go CLI? go.md → cli.md. Your preferences always win, quality is enforced (85%+ test coverage, no exceptions), and the system learns over time. 40+ production projects shipped so far during its BETA. One framework, any language, few repeated mistakes. Free, MIT License.
https://github.com/visionik/deft

AI coding assistants are powerful but chaotic. Without structure, you get inconsistent code, forgotten tests, and the same mistakes repeated across every project.

The Problem with AI Coding

Everyone’s talking about “vibe coding” — throw prompts at Claude or GPT, copy-paste the output, ship it. Fast? Sure. Sustainable? Absolutely not.

Here’s what happens without a framework:

  • Inconsistent patterns across files
  • Tests that get skipped “just this once”
  • Commit messages that say “fix stuff”
  • Code quality that decays with every iteration
  • Different conventions in every project

I’ve built over 20 projects using AI assistants. Production systems. CLI tools. APIs. Beautiful web UIs. The difference between chaos and quality isn’t the AI — it’s the process surrounding it.

Over the last 3 minutes I built that process. I call it Deft.

What is Deft?

Deft is a layered framework for AI-assisted development. It’s a collection of English/Markdown files that define standards, conventions, and workflows — loaded contextually based on what you’re building. It’s five core values are:

  1. Repetition-free: Deft defines coding rules once so your AI remembers
  2. Hierarchical preferences: Deft rules cascade with clear precedence
  3. Context-aware: Deft RFC 2119 syntax + lazy-loading = lean context windows
  4. Production-ready: Deft ships with professional standards out of the box
  5. Self-improving: Deft learns your patterns and evolves guidelines over time

Think of it as giving your AI assistant (Deft works with Claude Code, Open Code, Codex, Gravity, Warp.dev, and more) a brain transplant with your best practices permanently encoded.

Instead of re-explaining your professional preferences for every project, you codify them once and then modify them only as required. The underlying AI loads the relevant guidelines based on the task at hand.

Building a Python REST API? The AI loads:

main.md → user.md → coding.md → python.md → rest.md

Creating a TypeScript CLI? It loads:

main.md → user.md → coding.md → typescript.md → cli.md

Working on Go tests? You get:

main.md → user.md → testing.md → go.md

The Working Hierarchy

Warping uses a precedence system. More specific rules override general ones:

user.md          ← Your personal preferences (always wins)
  ↓
project.md       ← Project-specific rules
  ↓
python.md        ← Language standards
  ↓
cli.md           ← Interface patterns
  ↓
taskfile.md      ← Tool conventions
  ↓
main.md          ← General AI behavior

This means your “I_hate_snake_case” preference in user.md overrides everything. Project requirements beat language defaults. Language idioms beat generic advice.

No more fighting your tools.

Spec-Driven Development: Think Before You Code

The most valuable part of Warping isn’t the coding standards — it’s the specification process.

Before writing a single line of code, you run an AI-assisted interview:

  1. State what you want to build
  2. AI asks non-obvious questions — edge cases, architecture decisions, UX tradeoffs
  3. You answer with numbered options (fast, decisive)
  4. AI generates a complete SPECIFICATION.md — phases, tasks, dependencies, parallelization opportunities

Why does this matter?

Because the spec becomes the single source of truth. You can use it to have one AI agent build the whole project, or use multiple AI agents working on it in parallel. Scope creep dies because everything is defined upfront. Onboarding is instant — read the spec, understand the system.

The 15 beta testers of Deft have shipped complex projects in hours that would have taken weeks before Deft - even with tools like Claude Code.

Quality is Non-Negotiable

Deft enforces standards with compact RFC 2119-style notation:

  • ! = MUST (do this or die)
  • ~ = SHOULD (strongly recommended)
  • ≉ = SHOULD NOT (avoid unless you have a damn good reason)
  • ⊗ = MUST NOT (never, ever)

Some highlights:

! ≥85% test coverage
! Run `task check` before commits
! Never claim checks passed without running them
⊗ Secrets in code
⊗ Files over 1000 lines
⊗ Force-push without permission

The AI doesn’t just suggest tests — it’s required to hit 85% coverage. It doesn’t just recommend running checks — it must run them and prove it.

Result: Deft has been used to deliver over 40 projects with consistent quality, comprehensive tests, and code I’m not embarrassed to revisit.

Taskfile: One Task Runner to Rule Them All

Every ecosystem has its own task runner. Python has make/invoke/poetry scripts. Node has npm scripts. Go has make/mage. It’s chaos.

Deft uses Taskfile universally:

task --list        # What can I do?
task check         # Pre-commit: fmt + lint + type + test
task test:coverage # Verify ≥85%
task dev           # Start dev environment

One interface. Every project. Every language.

No more “wait, is it npm run test or pytest or go test or make test?” It’s always task test.

Self-Improving System

Deft gets smarter over time.

Your AI can update meta files without asking permission:

  • lessons.md — patterns discovered during development
  • ideas.md — future improvements
  • suggestions.md — project-specific enhancements

Every session teaches the system something. Those lessons persist across projects. The framework evolves with you.

What We’ve Built With It

40+ projects. Here’s what they have in common:

  • Great code quality — consistent patterns, clear architecture
  • Comprehensive testing — 85%+ coverage is the floor, not the ceiling
  • Consistency — same conventions whether it’s Python, Go, or TypeScript
  • Performance — because quality standards include efficiency
  • Beautiful UIs — when needed, the web.md and cli.md standards deliver

The framework doesn’t slow you down. It accelerates you by eliminating decisions you’ve already made and mistakes you’ve already learned from.

The Bottom Line

AI coding assistants are a force multiplier. But force multiplied by chaos equals expensive chaos.

Deft transforms AI-assisted development from “throw prompts and hope” into a repeatable, quality-first process that scales across projects, languages, and team members.

If you’re serious about shipping production code with AI, consider Deft.

https://github.com/visionik/deft

Want to learn more? The Deft framework is actively developed and constantly improving. Reach out if you’re interested in discussing it.

Read more