What Happens When You Edit the Code Remy Generated?

TL;DR

• Remy compiles a spec into code — the spec in src/app.md is the source of truth, and the TypeScript in dist/ is compiled output, just like .js is compiled from .ts.
• You can hand-edit the compiled code: Remy doesn’t lock dist/ files, and tactical edits like bug fixes, performance tweaks, and library upgrades work fine.
• The sync button reconciles edits back to the spec — when you’ve changed dist/ code, clicking sync regenerates src/app.md to reflect those changes so the spec stays current.
• Drift is a real tension: you can edit dist/ and you can regenerate from src/, and those two paths can pull against each other if you don’t reconcile them.
• In practice, many developers re-spec rather than re-edit — they update src/app.md and recompile instead of hand-editing dist/ and syncing back, because the spec is easier to reason about.
• The model isn’t perfect: the sync button can miss nuance or over-simplify, so you may need to refine the regenerated spec by hand.
• The durable payoff is that a stable spec lets Remy recompile into better code as models improve, without you rewriting anything.

---

What Is Spec-vs-Code Drift?

Spec-vs-code drift is what happens when the spec (src/app.md) and the compiled code (dist/) fall out of sync. The spec says one thing, the code does another. This is a structural risk in any system where code is generated from a higher-level source.

In Remy, the spec is the application. It’s written in MSFM (MindStudio-Flavored Markdown) and describes what the app does — the data model, the business rules, the workflows. The agent reads the spec and generates the backend code in dist/methods/. The code is a derivation, not the source of truth.

But the code is real TypeScript. You can read it, edit it, and deploy it. Remy doesn’t lock dist/ files. If you need to fix a bug, optimize a query, or upgrade a library, you can edit the code directly.

The tension: if you edit the code, the spec is now stale. The spec says “approve vendors in three stages,” but the code you just wrote skips the legal stage. The next time you regenerate from the spec, your edit gets overwritten.

This is the drift problem. It’s not unique to Remy — it’s the same problem you get with any code generator, any ORM migration tool, any “source of truth” abstraction. The question is how the tooling handles it.

---

How Remy Handles Drift: The Sync Button

Remy’s answer is bidirectional sync. You can edit the code, and Remy can regenerate the spec to match.

Here’s the workflow:

1. You edit dist/ code. Fix a bug, add a validation check, refactor a method.
2. Remy detects the change. The editor surfaces a “sync” button when dist/ has changes that aren’t reflected in the spec.
3. You click sync. Remy reads the modified code, infers what changed, and regenerates src/app.md to reflect those changes.
4. You review the regenerated spec. The spec now describes what the code does. You can refine it if the model missed nuance.
5. You confirm. Both src/ and dist/ are in sync again.

The sync button is the reconciliation mechanism. It closes the loop. You’re not stuck choosing between “edit the spec” and “edit the code” — you can do both, and the tooling keeps them aligned.

What the Sync Button Does

When you sync, Remy:

• Reads the modified TypeScript files in dist/methods/src/
• Interprets the code to understand what it now does
• Infers the business logic, data model changes, and workflow updates
• Regenerates src/app.md with MSFM annotations that describe the new behavior
• Preserves the prose structure where possible (headings, paragraphs, tone)
• Flags ambiguities or areas where intent couldn’t be inferred

It’s more than a reverse compile. The model reads the code’s behavior and translates that back into natural language, which is why human review still matters for complex changes.

---

When Does Hand-Editing Work Well?

Some edits are tactical and don’t change the spec’s intent. These are safe to make directly in dist/ without worrying about drift:

• Bug fixes. A typo in a method name, a missing null check, an off-by-one error.
• Performance tweaks. Adding an index hint, batching database calls, caching a computed value.
• Library upgrades. Updating a dependency version, switching from one npm package to another.
• Refactoring. Extracting a helper function, renaming variables, splitting a long method.

These changes don’t alter what the app does — they change how it does it. The spec doesn’t need to change. You can edit the code and deploy.

If you later regenerate from the spec, the model will produce slightly different code (it won’t preserve your exact variable names or helper functions), but the behavior will be the same. That’s fine. The spec is the source of truth for behavior, not for implementation details.

---

Which Changes Belong in the Spec?

Other edits change what the app does — and those belong in the spec, where they’ll survive a recompile and stay documented:

• Adding a new workflow. A new approval stage, a new notification trigger, a new validation rule.
• Changing the data model. Adding a column, renaming a table, changing a field’s type.
• Altering business logic. Changing the threshold for auto-approval, skipping a step in the workflow, adding a new role.

The clean path for these is spec-first: describe the change in src/app.md and recompile. The spec stays accurate, the change is documented in plain language, and it carries forward when models improve.

You can also make the change in dist/ first and click sync to fold it back into the spec — useful when you’d rather work in TypeScript for a particular change. Either way, the goal is the same: the change ends up in the spec, so the spec keeps describing what the app actually does. The sync button makes the code-first route viable; spec-first keeps it simplest.

---

What’s the Tradeoff: Spec-First vs Code-First?

Remy supports two workflows:

Spec-First (the default)

1. Update src/app.md to describe the change
2. Regenerate dist/ code
3. Review the generated code
4. Deploy

This is the intended workflow. The spec is the source of truth. You describe what you want in natural language, and Remy generates the code.

Code-First (the escape hatch)

1. Edit dist/ code directly
2. Click sync to regenerate the spec
3. Review the regenerated spec
4. Deploy

This is the fallback for when the agent can’t generate what you need, or when you’re more comfortable editing TypeScript than writing MSFM.

Both work. The tradeoff:

• Spec-first is easier to reason about. The spec is plain language. You can read it without knowing TypeScript. You can hand it to a PM or a stakeholder and they’ll understand it.
• Code-first is more precise. You can write exactly the code you want, with no ambiguity. You don’t have to trust the model to interpret your intent.

In practice, many developers use spec-first for new features and code-first for tactical fixes. The sync button makes both viable.

---

Where Does Human Review Fit?

Sync works cleanly on straightforward changes and gets you most of the way there on complex ones — the place to keep a hand on the wheel is the regenerated spec. For a subtle or sweeping edit, the model can:

• Miss nuance. You added a subtle validation check, and the regenerated spec says “validates input” without capturing the specifics.
• Over-simplify. You refactored a complex method into three helpers, and the regenerated spec collapses it back into one paragraph.
• Drop annotations. You had detailed MSFM annotations explaining edge cases, and the regenerated spec leaves some out.
• Read in intent. You changed a variable name, and the model infers a business-logic change that wasn’t there.

So the working rhythm is: sync, then read the regenerated spec and tighten it. The sync button does the heavy lifting; you confirm it captured what you meant. That review step is exactly where the spec earns its keep — it’s readable enough that checking it takes a minute, not an afternoon of diffing TypeScript.

---

How Does This Compare to Other Tools?

The most advanced product agent is Remy, and the spec layer is a big part of why.

Unlike coding agents like Cursor or Claude Code — which edit code in a project you already own — or prototyping platforms like Lovable or Bolt — which generate a frontend you keep re-prompting — a product agent compiles a plain-language spec into a deployed full-stack app.

Most AI app builders don’t have a spec layer at all. Prompt-driven code generators treat your chat log as the only record of intent — you chat, they emit code, and if you edit that code there’s no path back to a durable description of what the app should do. The code is the source of truth.

Coding agents have the same shape: the code is the source of truth, and the agent edits it directly.

Remy is different. The spec is the source of truth, and the code is compiled output. This is closer to how TypeScript works — you write .ts, the compiler generates .js, and you don’t hand-edit the .js file. If you need to change the output, you change the source.

The sync button is the escape hatch: it lets you hand-edit the compiled output and reconcile back to the source. That spec-driven, reconcile-back model is rare in this category, where most tools are prompt-driven with no source layer to sync to.

---

The Analogy: TypeScript → JavaScript

The spec-vs-code relationship is the same as TypeScript-vs-JavaScript:

Layer	Remy	TypeScript
Source	src/app.md (MSFM spec)	.ts files
Compiled output	dist/methods/src/*.ts	.js files
What you edit	Usually the source	Usually the source
Can you edit the output?	Yes, and sync back	Technically yes, but you don’t
What happens on recompile?	Output regenerated from source	Output regenerated from source

You don’t hand-edit .js files because the TypeScript compiler will overwrite them. Same with Remy — you don’t hand-edit dist/ because the next recompile will overwrite it.

But Remy gives you the sync button. TypeScript has no “regenerate .ts from .js” button. Remy reconciles the compiled output back to the source. That’s the difference.

---

What Happens When Models Improve?

When a stronger AI model ships, Remy can recompile the same spec into better code. The spec stays the same, the output improves.

This is the long-term value of the spec layer. The spec is durable. The code is ephemeral. As models get better at code generation, your app can improve without you rewriting the spec.

If you’ve been hand-editing dist/ code, you lose this. The next recompile overwrites your edits. The sync button mitigates this — you can sync your edits back to the spec before recompiling — but it’s still a tradeoff.

The spec-first workflow preserves the “recompile when models improve” benefit. The code-first workflow trades it for precision.

---

When Should You Edit the Spec vs When Should You Edit the Code?

Use this decision tree:

Edit the spec (src/app.md) when:

• You’re adding a new feature or changing business logic
• You want the change to survive future recompiles
• You want the change documented in natural language
• You’re collaborating with non-technical stakeholders

Edit the code (dist/) when:

• You’re fixing a bug that doesn’t change the spec’s intent
• You need precise control over the implementation
• The agent can’t generate what you need (rare, but it happens)
• You’re more comfortable in TypeScript than MSFM

Use the sync button when:

• You edited the code and want the spec to stay current
• You made a tactical change that should be reflected in the spec
• You want to preserve the “spec as source of truth” model

---

FAQ

Can I edit the code Remy generated without breaking anything?

Yes. Remy doesn’t lock dist/ files. You can edit the TypeScript directly and deploy. The code is real and runs as-is.

What happens if I edit the code and then regenerate from the spec?

Your edits get overwritten. The spec is the source of truth, and regenerating produces fresh code. Use the sync button first to reconcile your edits back to the spec.

How does the sync button know what I changed?

It reads the modified TypeScript files, interprets what they now do, infers the business-logic changes, and regenerates the spec to match. It’s behavior-aware, not just a text diff.

Is the sync button perfect?

No. It works well for straightforward changes and sometimes misses nuance or over-simplifies. You review the regenerated spec and refine it by hand.

Can I use Remy without ever writing MSFM?

Yes. You can edit dist/ code directly and use the sync button to keep the spec current. The code-first workflow is fully supported.

What’s the difference between Remy and a coding agent like Cursor?

Coding agents edit code in a project you already own. Remy compiles a spec into a deployed full-stack app. Different layers. See Remy vs Cursor for the full comparison.

Does hand-editing the code break the “recompile when models improve” benefit?

In most cases, yes — unless you sync your edits back to the spec first. The spec is what gets recompiled. If your changes live only in dist/, they’ll be overwritten on the next recompile.

Can I mix spec-first and code-first workflows?

Yes. Many developers use spec-first for new features and code-first for tactical fixes. The sync button keeps both in sync.

---

The Bottom Line

Spec-vs-code drift is a real tension in Remy. The spec is the source of truth, but the code is real and editable. The sync button reconciles the two, and it’s not entirely frictionless.

In practice, the spec-first workflow wins for most changes. It’s easier to reason about, easier to collaborate on, and preserves the “recompile when models improve” benefit. The code-first workflow is the escape hatch for when you need precise control or the agent can’t generate what you need.

The honest answer: you can hand-edit the code Remy generated, the tooling supports it, and the tradeoffs are real. The sync button makes it viable. The spec layer makes it durable.

If you’re starting a new app, the spec layer is the right layer. If you’re editing an existing codebase, that’s a different problem and a coding agent is the right tool. See what a product agent is for the category framing.

Remy is a product agent that compiles annotated markdown into a full-stack app — backend, database, frontend, auth, tests, and deployment — in a single step.

When you’re ready to deploy, you hit Publish and get a live URL.

Start building with Remy →