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

[chaploud]

Thanks for digging in — I'll answer each honestly.

Do I make manual code changes?

Almost never. My part is steering in words — "resolve this debt," "refactor this" in the terminal — and the agent writes the code. Editing code by hand is genuinely rare.

Models / local models

• Large, complex tasks → Fable 5; lighter tasks → Opus 5.
• No local models.

Cost, and whether it runs 24/7

• Claude Max 20x ($200/month, ~¥33,000).
• But it can't run around the clock. Token consumption is heavy and I hit the weekly usage cap regularly. It's not "set it loose and it runs forever" — I pace it against the limits.

Replicating the process

My .claude/ + .dev/ are readable, so copying them as a starting point is fine. But rather than mirroring my scaffolding, I think it's better to have the AI set the project up for you — that way the latest practices fit your project. Start with the official /init to seed CLAUDE.md, then ask the agent to "research current best practices for autonomous development and self-maintenance, and set this project up." For authoring skills there's the skill-creator plugin, and for team ramp-up the built-in /team-onboarding command.

That said, honestly, some hands-on iteration is unavoidable early on — trying behaviours repeatedly, mechanizing the ones that work, tuning skills, and checking the agent actually does what you intend. The rails don't assemble in one shot; they emerge from that loop.

One note for you: this repo forces Japanese chat via outputStyle in settings.json, so if you want to work in English, override it in settings.local.json (code, commits, and docs are all English already).

Does this setup work when others join?

The most important question, so — honestly. I actually just audited both repos for exactly this ("could a stranger reproduce it from a fresh clone?") and logged the results as debt (ClojureWasm D-565 / zwasm D-526). The answer splits in two:

• ✅ The artifacts and gates are collaboration-ready. A fresh clone builds, tests, and gets the full CI gate (multiple OSes on GitHub's runners) with zero host-specific setup — Nix pins the toolchain (Zig 0.16), deps are URL+SHA-pinned, and CI runs the same gate as local, so even a fork PR gets full gating.
• ⚠️ The AI-operating scaffolding is still solo-optimized. The agent workflow assumes my personal environment (reference clones, SSH gate hosts, global config, forced-Japanese chat) and has some doc staleness. I just surfaced all of that and filed it as debt.

So: the code-and-test foundation is ready for collaboration; the way the AI is driven is still mine alone — and that's what I'm now working through the debt to fix.

A guide / video

No written guide yet. But I'm planning to record a video of implementing one feature myself — that'll probably answer the workflow questions best. I'll share it when it's done.

Ask anytime if something's unclear. Good luck getting it running on your own projects!

[chaploud]

@ieugen

Here's the video I mentioned.

It only covers the opening — handing the red CI to the agent, up to the first diff appearing. Running the whole thing takes 1–2 hours with the investigation, tests, and gate, and most of that is waiting, so a full-length recording wouldn't be watchable.

• The subject is a real CI failure: the GC-torture e2e went red on x86_64-linux only (the macOS leg passed, so it's Linux-specific).
• Left is the agent, right is the working-tree diff, live.
• The first and last 30 seconds are real time; the middle is 15x.

The cause turned out to be a window where a worker's thread registration races the GC's stop-the-world. The investigation that got there is far longer than what the video covers.

demo_edited_small.mp4