Architect Clojure Interactive Programming

An agent for REPL-driven Clojure development that enforces a strict REPL-first workflow: every change is explored and tested in the REPL before modifying source files, maintaining architectural integrity through interactive feedback loops.

When to Use This Agent

Choose Clojure Interactive Programming when:

• Developing Clojure or ClojureScript applications using REPL-driven workflow
• Debugging Clojure code by evaluating subexpressions interactively
• Refactoring Clojure namespaces while maintaining pure function boundaries
• Exploring libraries and APIs interactively before committing to an approach
• Working with Clojure web servers, data pipelines, or concurrent systems

Consider alternatives when:

• Writing Clojure scripts that don't benefit from interactive development
• Working on non-Clojure JVM languages like Java or Kotlin
• Deploying or operating Clojure applications without code changes

Quick Start

Copy
# .claude/agents/clojure-interactive.yml
name: Clojure Interactive Programming
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are a Clojure interactive programming expert. Always use
  REPL-first development: test in the REPL before modifying files.
  Evaluate subexpressions instead of using println. Fix root causes,
  never workarounds. Maintain pure functions and proper namespacing.

Example invocation:

Copy
claude --agent clojure-interactive "Fix the data transformation
  pipeline in src/app/transform.clj - the nested map operation
  is producing nil values for some input shapes"

Core Concepts

REPL-First Workflow

1. Read source file → understand current implementation
2. Start REPL or connect to running REPL (nREPL, socket REPL)
3. Load namespace → (require '[app.transform :as t] :reload)
4. Evaluate subexpressions → isolate the problem
5. Develop solution incrementally in REPL
6. Once verified, update source file
7. Reload namespace and run tests

Subexpression Evaluation Strategy

Copy
;; Instead of adding println:
(defn process-data [items]
  (println "items:" items)          ;; DON'T do this
  (->> items
       (map transform)
       (filter valid?)))

;; Evaluate subexpressions in REPL:
(def sample-items [{:id 1 :value "test"} {:id 2 :value nil}])

;; Test each step independently
(map transform sample-items)        ;; Check transform output
(filter valid? (map transform sample-items))  ;; Check filter

;; Find the problem precisely without modifying source

Namespace Management

Operation	Command	When to Use
Load	(require '[ns] :reload)	After file changes
Reload all	(require '[ns] :reload-all)	After dependency changes
Remove	(remove-ns 'ns)	Stale definitions
Refresh	(clojure.tools.namespace.repl/refresh)	Full codebase reload
Find	(ns-publics 'ns)	Explore namespace API
Source	(clojure.repl/source fn-name)	View function source

Configuration

Parameter	Description	Default
repl_type	REPL connection method	nREPL
repl_port	Port for REPL connection	7888
test_runner	Test framework	clojure.test
reload_strategy	Namespace reload approach	:reload
data_inspection	Pretty-print REPL output	true
max_eval_time	Timeout for REPL evaluation	30s
cljs_env	ClojureScript environment if applicable	None

Best Practices

1. Never modify a source file without testing the change in the REPL first. The REPL is your primary development tool, not an afterthought. Evaluate the expression you plan to write, verify it produces the expected output, then copy it to the source file. This catches errors before they enter your codebase and builds confidence in every change.

2. Evaluate subexpressions instead of adding print statements. When debugging, thread your data through each step of the pipeline individually in the REPL. This shows you exactly where the transformation goes wrong without polluting source code with debugging artifacts that you'll need to remember to remove later.

3. Keep functions pure and push side effects to the edges. Pure functions are trivial to test in the REPL: pass in data, check output. Functions with side effects require setup, teardown, and mocking. Design your namespaces so that core business logic is pure, with IO operations isolated in a thin outer layer that's simple enough to verify by inspection.

4. Use rich comment blocks for development snippets. Place (comment ...) blocks at the bottom of your namespace files with REPL exploration code. These serve as executable documentation and provide starting points for anyone who works on the code later. They're ignored by the compiler but preserved in the source for future reference.

5. Reload namespaces carefully after structural changes. When you rename functions or change a namespace's public API, stale definitions linger in the REPL. Use remove-ns followed by a fresh require to get a clean state. For large dependency chains, clojure.tools.namespace.repl/refresh handles the reload order correctly.

Common Issues

Stale definitions in REPL after renaming or removing functions. The REPL retains all evaluated definitions until the JVM restarts. When you rename process-data to transform-data, the old process-data still exists in the REPL's namespace. Use (ns-unmap *ns* 'old-name) to remove specific symbols, or (remove-ns 'ns) followed by a fresh require to fully reset the namespace.

REPL becomes unresponsive during long-running evaluations. Always wrap potentially slow operations with timeouts: (deref (future (slow-fn)) 5000 :timeout). For infinite sequences, use (take n ...) before evaluating. If the REPL is stuck, interrupt the evaluation (Ctrl+C in most REPL clients) rather than restarting the entire process, which loses your accumulated state.

Stack overflow errors in recursive functions. Clojure does not optimize tail calls automatically. Use recur for tail-position recursion, lazy-seq for lazy recursive sequences, or trampoline for mutual recursion. Test recursive functions in the REPL with small inputs first, incrementally increasing size to find the breaking point before deploying with production-scale data.