How is development done?

[ieugen]

Hi, I've been watching the project for some time and installed it locally but did not have time to use it for anything yet (very little personal time until end of year :( ).

I am intrigued about the development process. I suspect you are using AI a lot - which seems very interesting and also causes some internal conflict.

Can you share your experience and your workflow?
How do you iterate, what tools do you use? Etc. Your work here and my beloief that you are using AI made me very curios about agentic AI for coding.
My main concern with AI in coding is with software maintenance at this point, but I did not use it for any project yet. Maybe next year :).

Thanks,
Eugen

[chaploud]

Thank you for taking an interest in ClojureWasm! Please excuse the AI-translated reply.

Yes — I lean on AI heavily; honestly, most of the code is written by an agent (Claude Code). But the interesting part isn't "AI writes code" — it's the rails that keep AI-written code from rotting. The software maintenance concern you raise is exactly the right question. One important premise: this is not greenfield work but a re-implementation (rebuilding Clojure on top of Wasm), so behaviour is anchored to an official reference by construction.

1. "Finished-form cleanliness" outranks everything

• Over shipping fast or avoiding rework, the top priority is whether the final shape is right. When a plan collides with that, the plan gets rewritten — not the shape.
• In the tree: .dev/principle.md (a Bad-Smell catalogue + four depths of revision) and .dev/project_facts.md (human-declared invariants — the top-level "law" the AI may not rewrite on its own).

2. Decisions are never lost — ADR / AD / debt

• ADRs (decision records): ~175 under .dev/decisions/, each with a status lifecycle and a mandatory "Alternatives considered" section.
• AD (Accepted Divergence): .dev/accepted_divergences.yaml — deliberate deviations from Clojure are ledgered, so "a bug" and "an intentional difference" never get confused.
• Debt ledger: .dev/debt.yaml. Since this is a re-implementation, "what to do next" == closing debt. The loop self-selects easiest-first and updates the ledger in the same cycle the work lands.

3. Per-task quality — a Bad-smell sensor & a Devil's advocate

• Quality is enforced not as an after-the-fact review but as an interrupt during editing: the moment something feels like "I'll fix it later / let me take a shortcut," the edit stops and the fix lands then and there.
• Devil's advocate: for any non-trivial design decision, a separate-context subagent is required to argue the opposite case, and its alternatives are recorded verbatim in the ADR. It's a deliberate countermeasure to the goal-drift that AI momentum tends to cause.

4. Always anchored to an official reference (because it's a re-implementation)

• No home-grown behaviour: "the correct behaviour always lives upstream (JVM Clojure)" is codified.
  • .claude/rules/clojure_spec_citation.md / textbook_survey.md / no_jvm_specific_assumption.md
• Differential oracle: the real clojure runs alongside, and diffs become a corpus → test/diff/clj_corpus/ (226 files, mechanically re-checked).

5. Don't trust — enforce mechanically (this is the real answer to maintenance)

• Neither the AI nor a human "keeps to the rails by good will" — hooks physically block violations.
  • The check_*.sh scripts (29 of them) under scripts/ are wired into PreToolUse hooks + git hooks via .claude/settings.json.
  • No push without a Smell-audited: line; no quiet edits to the ROADMAP; no solo AI edit of an invariant; no breaking the dual-backend parity oracle.
  • git commit --no-verify / force-push / reset --hard are denied outright — circumventing the hooks is itself blocked.
• Tests run as a two-tier gate (per-commit smoke / batched full / a full gate on push CI).

6. The zwasm layer underneath — same rails, a different official spec

(this may be close to your cherry-wasm-demo)

• cljw runs on top of a from-scratch Wasm engine, zwasm. zwasm is a sibling project that deliberately mirrors the same methodology, and it is disciplined against the official W3C WebAssembly spec:
  • zwasm/.dev/spec_pin.yaml (pins the SHAs of WebAssembly/spec and testsuite, plus a drift gate)
  • zwasm/test/spec/ — 461 official .wast conformance files, 616 in-code spec citations, and interp/JIT/AOT & 3-host differential testing.
  • zwasm/.dev/reference_clones.md explicitly notes it "mirrored ClojureWasm's procedural template."
• The two are joined by a version pin: build.zig.zon (zwasm v2.3.0) plus a capability ledger .dev/zwasm_capabilities.md.
• In short: the same rails applied to two runtimes (a Clojure runtime and a Wasm engine), each pinned to its own official spec.

An honest caveat

• The scaffolding itself has an upkeep cost (a periodic audit sweeps out stale text, lies, and false positives). The trade-off is deliberate: cost is spent on the discipline of maintaining the rails rather than on "going fast with AI."
• And this is one project's answer, not a team-scale proof. That said, my working impression is that the maintenance you worry about is decided more by rail design than by model cleverness.

Happy to go deeper on any part. Have fun with it!

[ieugen]

thanks @chaploud ,

(no AI bellow)

You opened a lot of questions :)

Do you also make manual code changes?
How is this setup compatible with other people working on the project?

How much does it cost and how could I replicate your process?
Are you using any local models?

Is there a guide (text/video) on how to go about implementing the process?

I do have a Claude Code subscription from work that I would like to use.
I do have some projects that I would like to work on.

If you are into that, I guess a video of you showing how you go about implementing a feature would answer a lot of the questions.

Thanks,
Eugen