I think the reverse direction is more important: taking a massive complex problem/codebase and decomposing it to short pseudocode. Then you could edit the pseudocode and compile it back into the system.
That's the way software engineers working on large projects work anyway: you first gather context on the state of the system and read it at a level you can understand. Then you propose a change on the simplified representation, and then holistically update the machine-runnable format ("implementation").
I'd be interested in tools that formalize/automate this process more.
Afaik there's no language - the pseudocode can be written however you want. And the costing money to compile? If you're prompting an llm you're already doing that, just with prose instead of pseudocode. I'm not sure this approach is a good idea, but it might be - and imo it's worth trying :)
I think "the pseudocode is persisted alongside the generated code" just reinvented jira/linear tickets and PR descriptions. We have ways of using git and tracing the code write to the thought process behind it.
I’ve been thinking about something along these lines for some time. I really like the direction of this.
The challenge I see more broadly is we (as engineers now empowered by LLMs) are trying to find the right level of abstraction to operate in. Writing long form sentences and (sometime) reviewing the output feels too far away. But having an LLM work directly with you in an IDE feels too close to “the old way”.
Personally for me the approach here still feels a little too close to the lower level old way, but it’s better than the two approaches above.
Right level of abstraction is a good way of putting it. It's basically like creating a custom DSL, but flexibility of LLMs allow the DSL to be ad-hoc.
At what point will you need formal rigid syntax? Or is not having rigid syntax the point? If the latter, how much "informational noise" or ambiguity can you inject before the "DSL compiler" gets confused?
Scaling is another bit. Convertible Psuedocode a great pattern for writing functions, but is it useful for writing modules? If you're writing a paragraph to change behavior of a function, you're underutilizing LLMs. Paragraphs are best for spec'ing modules, and the LLMs already fill in the blanks. Not sure if it would be faster to psuedocode the entire module (although maybe just the interface would be a sweet spot...)
Yeah exactly. The module/directory level is currently untested. I'm working on a desktop version so I can talk to a file system, and then I'll be able to explore those problems.
My guess is that if you simply write `use some_fn from $repo/some/path`, the LLM _should_ be smart enough to infer in most cases. But we'll have to see how reliable that is.
What I find interesting about this + a random bucket of associations because I’ve fallen under the spell of Satan’s Lettuce:
Just a few days ago someone was talking about a machine - human patois.
This (your project) sits somewhere between Lean and BDD cucumber syntax.
At the same time Claude spits out phrases like “a container paying the price of -42px”.
Recently I was listening to a lecture about metaphor in poetry, the misconception that poems are riddles whereas we use metaphors all the time in our language because they convey the meaning more precisely.
Why not just put an instruction into your favorite harness’ system prompt: “If I give you pseudo code, spell out my intent, and then write and test it in real code.”
Not a dumb question - you can totally do this. I was doing this for a while. Before Claude Code really took off, this was my primary way to use Cursor. I'd write some pseudocode, highlight it, and just write to the AI "make it real". Works like a charm.
The issue is that with very large or complex codebases, you tend to forget what was AI generated and what was written by a human. And it's also extremely tedious and difficult to read AI generated code. So if you want to _understand_ a complex bit of code, the natural tendency is to ask an agent to summarize it for you. This can work but also has lots of problems.
What you really want is a system that persists both your written intent, and the actual source code. And you want to provide a source map between them, so that you can understand which bits of human pseudocode are responsible for which bits of generated code.
The real value is in persisting your expressed intent.
I think the idea of having a human-written persistent document describing the operation of the code is a great idea. This document acts as the prompting interface instead of the chat window and changes can still be tracked. Surely something as simple as a skill.md can be made for such a setup, right?
I think the pseudocode style is a seperate axis to this setup.
What about multi-file / larger changes? How would you express files being connected, imports, and exports? Or are you thinking the hz files are disposable per change?
The intention is for the files to persist, and I didn't mention it, but a core part of the system is that the editor persists source maps. So at any point in time, you can map any generated line back to the line of pseudocode that generated it.
I'll be looking into multi-file stuff soon - it's an interesting can of worms to think through.
curious if you’ve tried Kiro or spec-driven development? that seems like it would solve at least some of the issues you raised with agent based development, albeit in a different way without the emphasis on pseudo code
yeah in the blog post I should have outlined the things I first tried to solve the problem. I tried a variant of gherkin rules, using them for the behavioral spec for a project. It works reasonably well, but without a direct source map from the rules to the code, you still end up with a very difficult-to-understand codebase.
A good commit message is not a record of human intent, it's a record of changes in human intent. You can read a change log to see the evolution of a codebase, sure.
But before AI arrived on the scene, source code was a single artifact that directly expressed the intended behavior of a piece of software as it currently exists. After AI, the artifact is still there, but it's no longer the true record of human intent.
> Welcome to my Github! I'm a web engineer who's been building front-ends since 2009. Most of my work is either closed source or behind paywalls, but here is where I tinker on side projects in my spare time.
No need to dismiss the person - you can just say you don't like the approach
not sure if the hz file artifact is needed, you can enter pseudocode directly into chat or even on an existing code file and with minor comment agents will be able to work with it. i write this type of pseudocode to existing code files often to great results.
Yes, I also wrote this kind of pseudocode. But to make full use of it, you'd want to persist it, and to maintain a map between the lines of your pseudocode and the lines of your real code. It's not practical to do this manually, you'd want these mechanics built into your editing system.
I just use a lot of folders, like folder for ever class and manager class with it and anything else. So its kind of organized by folders like plugins. Much easier to reason about. The biggest problem is the central class that glues everything is now 30 thousand lines, but its mostly repetitive delegation, init update, draw, delete. Still should be some nicer solution than having a huge class in center.
Definitely an approach worth exploring! I actually started to look into semi formal spec language like Quint because I wanted something more structured then prose, so I feel like this goes into the right direction.
Writing fizzbuzz requires that you understand algo + you credit card, while agent requires only your credit card. I believe most of people will pick the 2nd one.
Yes for many non-technical people who are building stuff for the very first time, this is absolutely true. Natural language will always be easier for them. But experienced engineers are wanting to use AI for very complex codebases, and AI struggles significantly beyond a certain point.
Would need to try out in a complex project to have opinion. However I already see few problems.
Slower development due this loop of generating code from you mini spec. I would snap and start writing code at one moment.
Different agent different code, off by one errors that agent deducts itself, and you miss because spec doesn't force you to write correct code. Those might be caught by unit tests, but then why not generate code based on tests, as uncle Bob does...
You seem to be conflating two things: how to prompt, and how to share sessions. You can already use pseudo-code today if you want to. As for sharing, you can commit (a link to) it, use `git notes` (as I do), or a service like entire.io.
I think you should work on your differentiation. The session management stuff is the greater concern, in my opinion; pseudo code is not a novelty.
Help me understand - what do you mean be "share sessions"? And yes you can definitely use pseudo code today - that in and of itself is not a novelty at all. The specific novelty is the fact that the editor assumes two equivalent sources - your pseudocode which acts as a prompt, and the source code generated from that prompt. The editor also provides a source map for the two, so that as a codebase grows in size and complexity, it's trivial to link a specific section of code back to a human's written intent.
I see, thank you. So the difference in this case is that you're effectively writing very terse documentation. If I as a human interpreter want to understand why a range of code came into existence, I'm very unlikely to want to read another engineer's session. I'd have no way of knowing how far back into the session to read - some conversations can be very complicated. It also requires persisting everyone's sessions, which I'm sure is a pretty pricey problem. The truth is that for a given chat session, the messages themselves aren't extremely valuable, because they're part of the working development of the code.
What I'm after is a condensed distillation of human intent using semi-formal symbolic language, which should be vastly easier to read and understand for engineers and teams.
I think the reverse direction is more important: taking a massive complex problem/codebase and decomposing it to short pseudocode. Then you could edit the pseudocode and compile it back into the system.
That's the way software engineers working on large projects work anyway: you first gather context on the state of the system and read it at a level you can understand. Then you propose a change on the simplified representation, and then holistically update the machine-runnable format ("implementation").
I'd be interested in tools that formalize/automate this process more.
I'm confused, it looks like you've just written a new terse language that now costs money to compile?
Afaik there's no language - the pseudocode can be written however you want. And the costing money to compile? If you're prompting an llm you're already doing that, just with prose instead of pseudocode. I'm not sure this approach is a good idea, but it might be - and imo it's worth trying :)
Yes, there's no language. And exactly - we're effectively already doing this, but with waaay more words.
I think "the pseudocode is persisted alongside the generated code" just reinvented jira/linear tickets and PR descriptions. We have ways of using git and tracing the code write to the thought process behind it.
I’ve been thinking about something along these lines for some time. I really like the direction of this.
The challenge I see more broadly is we (as engineers now empowered by LLMs) are trying to find the right level of abstraction to operate in. Writing long form sentences and (sometime) reviewing the output feels too far away. But having an LLM work directly with you in an IDE feels too close to “the old way”.
Personally for me the approach here still feels a little too close to the lower level old way, but it’s better than the two approaches above.
Excited to see where you take it!
Right level of abstraction is a good way of putting it. It's basically like creating a custom DSL, but flexibility of LLMs allow the DSL to be ad-hoc.
At what point will you need formal rigid syntax? Or is not having rigid syntax the point? If the latter, how much "informational noise" or ambiguity can you inject before the "DSL compiler" gets confused?
Scaling is another bit. Convertible Psuedocode a great pattern for writing functions, but is it useful for writing modules? If you're writing a paragraph to change behavior of a function, you're underutilizing LLMs. Paragraphs are best for spec'ing modules, and the LLMs already fill in the blanks. Not sure if it would be faster to psuedocode the entire module (although maybe just the interface would be a sweet spot...)
Yeah exactly. The module/directory level is currently untested. I'm working on a desktop version so I can talk to a file system, and then I'll be able to explore those problems.
My guess is that if you simply write `use some_fn from $repo/some/path`, the LLM _should_ be smart enough to infer in most cases. But we'll have to see how reliable that is.
What I find interesting about this + a random bucket of associations because I’ve fallen under the spell of Satan’s Lettuce:
Just a few days ago someone was talking about a machine - human patois.
This (your project) sits somewhere between Lean and BDD cucumber syntax.
At the same time Claude spits out phrases like “a container paying the price of -42px”.
Recently I was listening to a lecture about metaphor in poetry, the misconception that poems are riddles whereas we use metaphors all the time in our language because they convey the meaning more precisely.
Dumb question:
Why not just put an instruction into your favorite harness’ system prompt: “If I give you pseudo code, spell out my intent, and then write and test it in real code.”
Not a dumb question - you can totally do this. I was doing this for a while. Before Claude Code really took off, this was my primary way to use Cursor. I'd write some pseudocode, highlight it, and just write to the AI "make it real". Works like a charm.
The issue is that with very large or complex codebases, you tend to forget what was AI generated and what was written by a human. And it's also extremely tedious and difficult to read AI generated code. So if you want to _understand_ a complex bit of code, the natural tendency is to ask an agent to summarize it for you. This can work but also has lots of problems.
What you really want is a system that persists both your written intent, and the actual source code. And you want to provide a source map between them, so that you can understand which bits of human pseudocode are responsible for which bits of generated code.
The real value is in persisting your expressed intent.
I think the idea of having a human-written persistent document describing the operation of the code is a great idea. This document acts as the prompting interface instead of the chat window and changes can still be tracked. Surely something as simple as a skill.md can be made for such a setup, right? I think the pseudocode style is a seperate axis to this setup.
Hmm. Interesting idea.
What about multi-file / larger changes? How would you express files being connected, imports, and exports? Or are you thinking the hz files are disposable per change?
The intention is for the files to persist, and I didn't mention it, but a core part of the system is that the editor persists source maps. So at any point in time, you can map any generated line back to the line of pseudocode that generated it.
I'll be looking into multi-file stuff soon - it's an interesting can of worms to think through.
Having hz files also opens a really interesting idea of using them as a form of static analysis and CI validation.
Isn't this just spec-driven development in a different language?
curious if you’ve tried Kiro or spec-driven development? that seems like it would solve at least some of the issues you raised with agent based development, albeit in a different way without the emphasis on pseudo code
yeah in the blog post I should have outlined the things I first tried to solve the problem. I tried a variant of gherkin rules, using them for the behavioral spec for a project. It works reasonably well, but without a direct source map from the rules to the code, you still end up with a very difficult-to-understand codebase.
> There’s no reliable record of human intent.
Every engineer I have ever mentored got a lesson on how to write a good commit message that included this. This is exactly that.
Further Huzzah from skimming it over seems to be re-inventing documenting your code.
Together I can only surmise that the author is new out of school or has simply not yet worked on a team with good coding practices.
A good commit message is not a record of human intent, it's a record of changes in human intent. You can read a change log to see the evolution of a codebase, sure.
But before AI arrived on the scene, source code was a single artifact that directly expressed the intended behavior of a piece of software as it currently exists. After AI, the artifact is still there, but it's no longer the true record of human intent.
Two clicks from the article:
> Welcome to my Github! I'm a web engineer who's been building front-ends since 2009. Most of my work is either closed source or behind paywalls, but here is where I tinker on side projects in my spare time.
No need to dismiss the person - you can just say you don't like the approach
not sure if the hz file artifact is needed, you can enter pseudocode directly into chat or even on an existing code file and with minor comment agents will be able to work with it. i write this type of pseudocode to existing code files often to great results.
Yes, I also wrote this kind of pseudocode. But to make full use of it, you'd want to persist it, and to maintain a map between the lines of your pseudocode and the lines of your real code. It's not practical to do this manually, you'd want these mechanics built into your editing system.
I just use a lot of folders, like folder for ever class and manager class with it and anything else. So its kind of organized by folders like plugins. Much easier to reason about. The biggest problem is the central class that glues everything is now 30 thousand lines, but its mostly repetitive delegation, init update, draw, delete. Still should be some nicer solution than having a huge class in center.
This is basically a compiler, but we’re moving up a layer of abstraction.
Are we supposed to be able to read the examples with our eyes? It looks like black text on a very dark grey background on my iPhone.
EDIT: same on Firefox on my Mac (macOS Ventura).
Pushing a fix now - thanks for letting me know.
edit: fixed
I'd call this one Micropilot.
As in micromanagement.
Definitely an approach worth exploring! I actually started to look into semi formal spec language like Quint because I wanted something more structured then prose, so I feel like this goes into the right direction.
Writing fizzbuzz requires that you understand algo + you credit card, while agent requires only your credit card. I believe most of people will pick the 2nd one.
Yes for many non-technical people who are building stuff for the very first time, this is absolutely true. Natural language will always be easier for them. But experienced engineers are wanting to use AI for very complex codebases, and AI struggles significantly beyond a certain point.
Would need to try out in a complex project to have opinion. However I already see few problems. Slower development due this loop of generating code from you mini spec. I would snap and start writing code at one moment. Different agent different code, off by one errors that agent deducts itself, and you miss because spec doesn't force you to write correct code. Those might be caught by unit tests, but then why not generate code based on tests, as uncle Bob does...
With scale problems arise.
You seem to be conflating two things: how to prompt, and how to share sessions. You can already use pseudo-code today if you want to. As for sharing, you can commit (a link to) it, use `git notes` (as I do), or a service like entire.io.
I think you should work on your differentiation. The session management stuff is the greater concern, in my opinion; pseudo code is not a novelty.
Help me understand - what do you mean be "share sessions"? And yes you can definitely use pseudo code today - that in and of itself is not a novelty at all. The specific novelty is the fact that the editor assumes two equivalent sources - your pseudocode which acts as a prompt, and the source code generated from that prompt. The editor also provides a source map for the two, so that as a codebase grows in size and complexity, it's trivial to link a specific section of code back to a human's written intent.
Sharing sessions means providing full visibility into what you did with the agent to the team. See https://entire.io/ or https://usegitai.com/
You can already retrieve the session associated with a given line of code.
I see, thank you. So the difference in this case is that you're effectively writing very terse documentation. If I as a human interpreter want to understand why a range of code came into existence, I'm very unlikely to want to read another engineer's session. I'd have no way of knowing how far back into the session to read - some conversations can be very complicated. It also requires persisting everyone's sessions, which I'm sure is a pretty pricey problem. The truth is that for a given chat session, the messages themselves aren't extremely valuable, because they're part of the working development of the code.
What I'm after is a condensed distillation of human intent using semi-formal symbolic language, which should be vastly easier to read and understand for engineers and teams.