REPL-Driven Development

REPL-driven development is not just “I happened to type some code into a REPL.” It is a deliberate workflow:

• explore a problem interactively
• extract the useful code into source
• reload and retest in context
• keep the program restartable when needed

That is why experienced Clojure developers often work so quickly. They are not skipping structure. They are shortening the path between a design question and a verified answer.

The Core Loop

A strong REPL-driven loop looks like this:

1. start from a running REPL connected to the project
2. require the namespace you want to work on
3. evaluate a small expression or function
4. inspect the result
5. refine the code in the source file
6. reload the namespace
7. call the code again

This is different from the Java habit of treating a full application restart as the normal way to test every small change.

Use The REPL To Ask Specific Questions

The REPL is best when your question is concrete:

• What exact value shape comes back from this transformation?
• Which namespace needs to be loaded for this call to work?
• What does this function do on the edge case?
• Does this reload preserve the state I care about?

The official REPL-aided development guidelines make an important point here: the REPL is another user interface to your program. That is a powerful idea because it means you can create project code that exists specifically to support interactive work.

For example, it is common to define a development namespace with small helper functions for:

• starting a local system
• stopping it
• seeding data
• running ad hoc queries
• reproducing a bug scenario

That is often more maintainable than performing the same steps manually in a dozen slightly different ways.

Do Not Confuse Velocity With Progress

This is where many newcomers get into trouble.

The REPL makes small changes feel cheap. That is good. But the same cheapness can tempt you into wandering:

• trying arbitrary ideas without a plan
• patching live state until the session is no longer trustworthy
• learning lots of local facts without improving the real design

The official guidance is right to warn about this. The REPL can produce motion very easily. Progress still requires intent.

A good habit is to start a session with a written question:

• “Understand why this namespace reload fails”
• “Normalize this API payload into domain data”
• “Verify that this pure function handles three edge cases”

If you cannot state the question, the REPL may become a distraction instead of a development tool.

Save What Matters

The REPL is ephemeral. That is one of its strengths and one of its dangers.

If the session taught you something important, make that knowledge durable:

• move a useful function into a source file
• keep a runnable example in a (comment ...) block
• add a test that preserves a behavior you just discovered
• update project docs when a manual REPL sequence is actually a required workflow

If you fail to do that, the knowledge remains trapped in shell history and personal memory.

That is not team-friendly engineering.

Use A dev Namespace On Purpose

One of the most useful Clojure habits for non-trivial projects is keeping a development namespace that exists mainly for interactive work.

For example:

 1(ns my.app.dev
 2  (:require [my.app.system :as system]))
 3
 4(defonce running-system (atom nil))
 5
 6(defn start []
 7  (reset! running-system (system/start)))
 8
 9(defn stop []
10  (when-let [s @running-system]
11    (system/stop s)
12    (reset! running-system nil)))
13
14(defn restart []
15  (stop)
16  (start))

This kind of namespace does not replace architecture. It makes architecture easier to exercise from the REPL.

For a Java engineer, a good analogy is a very lightweight development control surface for the running system.

Prefer Reloadable Design Over Magical Sessions

REPL-driven development works best when the program is written so that pieces can be reloaded and restarted cleanly.

Helpful traits:

• a pure core
• explicit boundaries
• restartable system state
• side effects concentrated in a few places

Harmful traits:

• hidden global state everywhere
• side effects during namespace load
• one-time startup logic that cannot be repeated safely
• tangled initialization order

This is why REPL-friendly design often overlaps with good architecture. A system that can be restarted from the REPL is usually easier to test and reason about in general.

The REPL Is Not The Only Tight Feedback Loop

Another useful official reminder: the REPL is not the only interactive tool.

You may also use:

• test watchers
• editor-integrated evaluation
• hot-reloading test or UI tools
• linters and static analysis

A mature workflow usually combines these. The REPL is central, but it should not become an excuse to ignore other useful feedback loops.

A Practical Example

Suppose you are building an HTTP handler. A REPL-driven workflow might look like:

1. capture a realistic request map
2. write a pure function that normalizes it
3. test that function in the REPL
4. move it into the source namespace
5. reload the namespace
6. call the full handler with the sample request
7. if needed, restart the running system from your dev namespace

That is much more intentional than just repeatedly restarting the whole app and clicking around until something seems right.

Common Mistakes

• starting a REPL session without a concrete question
• keeping important knowledge only in the session
• building a workflow that depends on fragile hidden state
• assuming the REPL replaces tests and architecture work

The REPL should sharpen your workflow, not blur it.

Knowledge Check: Real REPL-Driven Development