Using Claude as an Execution Layer

Here is an unusual way to build software: instead of writing code that does things, you write markdown specs that tell Claude how to do things. The only "real" code is MCP tools that talk to system APIs.

We have been building Fazm this way for about a year. The CLAUDE.md tells Claude how to run builds, where configs live, test patterns - stuff that would normally be bash scripts or a Makefile. The actual code is just the MCP tools that talk to macOS APIs (accessibility layer, screen capture). Everything else is prompts and markdown files that Claude executes in sequence.

Why This Works

The iteration speed is the real win. When you want to change behavior, you edit a markdown file, not code. No compilation. No deployment. No type errors to chase down.

Traditional development:

1. Write code
2. Compile
3. Test
4. Debug type errors
5. Recompile
6. Ship

Markdown-spec development:

1. Edit the spec
2. Claude executes it
3. Observe the result
4. Adjust the spec

The feedback loop is dramatically tighter.

What the Stack Looks Like

CLAUDE.md          - project conventions, build instructions
specs/*.md         - feature specs in plain language
mcp-servers/       - thin wrappers around macOS APIs
  accessibility/   - read/write UI elements
  screencapture/   - grab screen frames
  whisper/         - voice transcription

The MCP servers are the only traditional code. They are thin wrappers - maybe 200 lines each - that expose macOS APIs as MCP tools. Everything above that layer is markdown that Claude interprets.

When This Breaks Down

This approach has limits:

• Performance-critical code still needs to be real code. You cannot markdown-spec your way to 60fps screen capture.
• Complex state management is hard to express in specs. Once you have enough interacting state machines, you need actual types and abstractions.
• Debugging is harder because the "code" is distributed across markdown files and Claude's interpretation of them.

For Fazm, roughly 70% of the behavior is spec-driven and 30% is traditional Swift code. The Swift handles the performance-critical pipeline (capture, process, execute). The specs handle everything else (what to capture, how to process it, what actions to take).

Getting Started

If you want to try this approach:

1. Start with your CLAUDE.md file - make it comprehensive
2. Identify the thinnest API boundary you can wrap in MCP tools
3. Write your first feature spec in markdown
4. Let Claude execute it and iterate

The key insight is that the spec is the product. The code is just plumbing.

---

Based on our experience building Fazm. Discussed in r/ClaudeAI.