diff --git a/instructions/clojure.instructions.md b/instructions/clojure.instructions.md index 483c4d3..b29fbbc 100644 --- a/instructions/clojure.instructions.md +++ b/instructions/clojure.instructions.md @@ -7,7 +7,7 @@ applyTo: '**/*.{clj,cljs,cljc,bb,edn.mdx?}' ## Code Evaluation Tool usage -“Use the repl” means to use the **Evaluate Clojure Code** tool from Calva Backseat Driver. It connects you to the the same REPL as the user is connected to via Calva. +“Use the repl” means to use the **Evaluate Clojure Code** tool from Calva Backseat Driver. It connects you to the same REPL as the user is connected to via Calva. - Always stay inside Calva's REPL instead of launching a second one from the terminal. - If there is no REPL connection, ask the user to connect the REPL instead of trying to start and connect it yourself. @@ -39,7 +39,7 @@ Docstrings belong immediately after the function name and before the argument ve ## Interactive Programming (a.k.a. REPL Driven Development) ### Align Data Structure Elements for Bracket Balancing -**Always align multi-line elements vertically in all data structures (vectors, maps, lists, sets, all code). Misalignment causes the bracket balancer to close brackets incorrectly, creating invalid forms.** +**Always align multi-line elements vertically in all data structures: vectors, maps, lists, sets, all code (since Clojure code is data). Misalignment causes the bracket balancer to close brackets incorrectly, creating invalid forms.** ```clojure ;; ❌ Wrong - misaligned vector elements @@ -73,7 +73,7 @@ Use `clojure.repl.deps/add-libs` for dynamic dependency loading during REPL sess (add-libs '{dk.ative/docjure {:mvn/version "1.15.0"}}) ``` -- Requires Clojure 1.12 or later +- Dynamic dependency loading requires Clojure 1.12 or later - Perfect for library exploration and prototyping ### Checking Clojure Version @@ -85,29 +85,18 @@ Use `clojure.repl.deps/add-libs` for dynamic dependency loading during REPL sess ### REPL Availability Discipline -**Never edit code files when the REPL is unavailable.** When REPL evaluation returns errors like "No available JS runtime", stop immediately and inform the user: - -``` -The REPL is currently unavailable. I cannot verify changes without REPL access. Please ensure the REPL is connected before proceeding with code modifications. -``` +**Never edit code files when the REPL is unavailable.** When REPL evaluation returns errors indicating that the REPL is unavailable, stop immediately and inform the user. Let the user restore REPL before continuing. #### Why This Matters -- **Interactive Programming requires working REPL** - Cannot verify behavior without evaluation +- **Interactive Programming requires a working REPL** - You cannot verify behavior without evaluation - **Guessing creates bugs** - Code changes without testing introduce errors -- **User wastes time** - Undoing speculative changes is frustrating -- **Trust erosion** - Making changes without verification undermines confidence - -#### When REPL Is Unavailable -1. **Stop immediately** - Do not proceed with code changes -2. **Inform the user** - Clearly state REPL is unreachable -3. **Wait for reconnection** - Let user restore REPL before continuing ## Structural Editing and REPL-First Habit - Develop changes in the REPL before touching files. - When editing Clojure files, always use structural editing tools such as **Insert Top Level Form**, **Replace Top Level Form**, **Create Clojure File**, and **Append Code**, and always read their instructions first. ### Creating New Files -- Use the **Create Clojure File** tool, with initial content +- Use the **Create Clojure File** tool with initial content - Follow Clojure naming rules: namespaces in kebab-case, file paths in matching snake_case (e.g., `my.project.ns` → `my/project/ns.clj`). ### Reloading Namespaces @@ -171,7 +160,7 @@ You can also use "inline def" when showing the user code in the chat, to make it ## Return values > print side effects -Prefer using the repl and return values from your evaluations, over printing things to stdout. +Prefer using the REPL and return values from your evaluations, over printing things to stdout. ## Reading from `stdin` - When Clojure code uses `(read-line)`, it will prompt the user through VS Code. @@ -322,9 +311,9 @@ Iterate with real data before editing files. ``` #### Benefits -- Verified behaviour before committing changes +- Verified behavior before committing changes - Incremental development with immediate feedback -- Tests that capture known-good behaviour +- Tests that capture known-good behavior - Start new work with failing tests to lock in intent ### Test Naming and Messaging