<written by a human being>

When an AI agent works with projects that lack a clear structure - examples of which I covered in the previous two posts - it's important to observe the process and watch what it's actually doing.

Agents typically don't attempt to read a file directly, because it can be quite large. For an average Bubble project, the file might weigh 15 megabytes of pure text - essentially a massive JSON file of colossal proportions. So instead of reading it straight through, the agent peeks at the first few lines, extracts an understanding of the structure, and then writes code - in Python, for example - to pull out the elements it needs using scripts.

This approach works, but again, only when the project is well-structured and follows a consistent hierarchy. When patterns repeat, code written for one page to extract, say, all footer elements will work for another page too - as long as the structure is identical. The agent will recognize this and efficiently locate the relevant spots and elements it needs to work with.

But if the structure is chaotic - like in my inherited project example, where a single page has dozens of reusable elements - that logic breaks down entirely. There's no pattern to find, and the agent simply can't identify something that works consistently across every page. In that case, it would have to write separate code for each individual page, which makes no sense whatsoever, since it would still need to actually read the JSON elements directly related to that page from the Bubble export, and only then write code around them.

In moments like these, you need to stop the agent, ask it to explain what's currently happening and what it's trying to do, and step in with your own cognitive toolkit. It's often easier to just open Bubble yourself, find the relevant page and element, take some screenshots, point to the specific field - so the agent can use that concrete data to zero in on exactly where the problem needs to be investigated.

And fair warning upfront: working with Bubble apps this way hasn't yielded major results for me personally yet, but in some cases I did find clues pointing to where a bug should be looked for - and then tracked it down myself inside the app.

<written by a human being>

Tasks related to digging through the Bubble app export mess are still extremely resource-intensive in terms of token consumption and AI agent limits.

Literally in a single bug-hunting session, Claude burned through 12% of my weekly limit and 100% of the current session limit - at which point I decided to stop and continue searching for the bug manually, because it was getting way too expensive. Plus I still needed Claude for several other tasks that day.

One more thing - here's how I actually handle these kinds of tasks. On my local machine I have a folder with repositories for different projects. Just like I create separate repositories for codebases, I create a separate folder for each Bubble project and drop the app export in JSON format right into its root.

I create a dedicated screenshots folder where I put (surprisingly) screenshots of the app itself, so the AI agent has fuller context to work with.

For example, if I'm hunting down a bug, I can take screenshots showing that bug, put them in a separate bugs folder, and point the agent in a fresh session at exactly the files you need it to read.

Obviously, you need to launch the agent from the project folder with access granted to it. From there it can work with files inside that folder - examining your screenshots, studying the JSON structure.

It helps enormously to write an agent instruction and action plan upfront - this really structures the work with any AI agent on the project. I'm planning to write about this in more detail in upcoming posts, by the way.

The worst way to find happiness is the one most people are using right now

Read more about The Science and Philosophy of Happiness: Practical Techniques for Lasting Contentment

<written by a human being>

Finally managed to get AI agents to work with Bubble apps, and it turned out to be simpler than I expected. The Bubble export as-is is minified JSON, and working with such a document is problematic for AI. It tries to write Python scripts to parse it, but there's only one line in the file - and you need to do some pre-processing first, which the AI somehow doesn't figure out on its own.

The solution is pretty straightforward: open the Bubble export in an editor that can format JSON, reformat it into standard multi-line pretty-printed JSON - not minified.

I use Notepad++ for this, do a pretty print and save it as a separate JSON file. This way we move away from the Bubble format, even though it's essentially just JSON. But now we have clean JSON - multi-line instead of squashed into a single string.

The file will be roughly twice as large in this format compared to the original, but at least it becomes readable for AI agents, and they handle it just fine - even though it's complex and has a lot of nested elements.

<written by a human being>

We keep making AI and Bubble work better together.

Based on analyzing several apps, I asked Codex (OpenAI's coding AI agent) to create a universal parsing schema that works for any Bubble project.

From now on, for any new Bubble project you're working with, take this schema and feed it as input to the agent. The easiest way is to place this file next to your app export in JSON format and tell the agent that the parsing schema is in this file, then ask it to understand how the app works - the export of which is in another JSON file - and help you solve a specific task, like finding a bug.

Things will go better and much faster if you also tell your agent exactly which element the bug is in. For example, I had an issue with saving an email in one of my apps. I opened Bubble on the page where that element was, selected it, and copied the five-character element ID from the address bar.

With this approach, the AI agent will quickly navigate to the right spot in the JSON file without scanning the entire document, and will immediately start working around that element - which significantly speeds up processing and reduces consumption of those precious tokens. Use it.

<written by a human being>

Systems Analysis and Artificial Intelligence

I've already written in one of my previous posts about how AI currently struggles to create diagrams in systems analysis notations directly. But we, being the lazy and true automators that we are, never settle for what we have and always look for ways to make it happen.

One part I've already successfully tackled is BPMN notation. BPMN already has a DSL (domain-specific language) that allows you to describe a diagram in XML format, which is then read by programs that render these diagrams.

So the task AI needs to perform is to generate XML - something it handles very well, because it's a clear structure, a sequential hierarchy, and relationships it can readily understand.

All you need to do is describe the business process in text form, the way it actually runs. In my case, for instance, I already had a text description in the form of an interview transcript - the kind that a systems analyst typically conducts when documenting business processes. This is done to find out exactly how things work from the perspective of the people directly involved in the process.

The meeting recording was processed by my scripts, which converted the audio to text. And based on that text, an AI agent - Claude, in this case - generated XML in BPMN format compatible with Bizagi, the tool I usually use to draw BPMN models.

Stop asking "How can I be happy?" and start asking "What does happiness mean to me?"

Read more about The Science and Philosophy of Happiness: Practical Techniques for Lasting Contentment

<written by a human being>

I honestly didn't expect to get a compatible version of BPMN scheme right away without having to either manually tweak it or explain how the model needed to be adjusted to open properly - but, to my surprise, the AI-generated BPMN file opened immediately, without a single error, without a single conflict, and was read by the program correctly.

All I had left to do was fix some arrows and block positions to make everything look neater, because spatial thinking is extremely difficult to express in XML format.

But nonetheless, at the next stage I even tried making edits to that diagram, which Claude handled beautifully - refining a certain part of the process and delivering an already-corrected XML file, which I successfully updated, and then manually polished the visual rough edges I wanted to clean up on the diagram itself, the ones affecting its visual readability.

So Claude earned yet another title and became my assistant - practically a full-fledged systems analyst. Not quite full-fledged yet, since we still have the IDEF0 challenge ahead of us.

<written by a human being>

Keep Codex Away from Your Computer, or How It Deleted Important System Services

Not too long ago, I wrote about how to fix Windows you can now just spin up a coding agent from the command line and hand it the right task.

That's actually what I did on my own machine - but the agent was Claude, and it nailed it. It operated surgically, yet with remarkable care: whenever it had any doubts, it asked first. It never deleted anything without my permission unless it was completely certain.

For instance, it would ask about specific programs and services, and explain exactly what each proposed change would mean. The whole cleanup went incredibly smoothly.

On a different machine, I decided to test the same task with Codex. I fed it the prompt that Claude had composed based on all the actions we'd taken during our previous system optimization session.

Codex handled cleaning out temp files from all the system folders without any trouble. Thankfully, I'd told it upfront not to touch anything in the Recycle Bin or the Downloads folder. It ran DISM and SFC procedures as well - successfully enough.

But then it got to the services - and that's where things went sideways. After analyzing and cleaning up what it considered "unnecessary" services, it came back and told me it had accidentally deleted critical system services responsible for Windows Updates, Defender, and other mechanisms essential to normal operation.

I'll be honest: my jaw hit the floor.
To be continued tomorrow.

<written by a human being>

Keep Codex Away from Your Computer [Part 2]

Read the beginning in the previous post.

So, I started asking Codex what would happen if I kept working without the system services it had deleted, and how they could be restored. Turned out, running without them wasn't safe.

What followed were several futile attempts to restore those services - from Codex's own log, from history, via SFC and DISM, even through a Windows ISO image. None of it worked.

Codex then concluded that the only possible way to recover them was to perform a system reinstall. Not a clean one, thankfully - the kind where you reinstall on top of an existing system without resetting the current user and data, essentially just restoring system files. Still, in my view that's a last resort, and I hadn't dealt with a Windows reinstall since upgrading to version 8. I really didn't want to go through with it - it takes a significant amount of time, requires reconfiguration, and demands a lot of attention.

After a few more rounds of interrogating Codex, we finally figured out that those services could actually be brought back through a System Restore point. We checked which restore points existed, picked the most recent one - created two days ago - restored from it, and verified the services: they were back. But along with them, every change made during that "optimization" session got rolled back too.

Tomorrow I'll write up the lessons I took from this and a couple of recommendations if you're thinking about trying this at home.

<written by a human being>

Keep Codex Away from Your Computer [Part 3]

So, here are my lessons from optimizing Windows with Codex.

First. Add a bit more paranoia to the initial prompt - it will give you more control over its actions. Since it mostly operates through scripts (it writes a script and then executes it in Bash), it’s better to require it to describe what the scripts actually do and to double-check the possible consequences before running them.

Second. Pay close attention to what is happening during the process. At first I gave it some freedom myself because it kept asking too many questions, but that ended up backfiring. Still, Codex didn’t really provide clear explanations of what exactly was happening at each step - it was mostly just generating scripts and executing them.

And finally, third - create a system restore point before making any changes with this computer master. If you have a restore point, you can roll back to it and restore everything to the previous state without affecting your local user files.

Or just let Claude Code handle the system optimization procedure instead of Codex.
I wish you no BSODs.

<written by a human being>

agent-instructions.md is a file that lives in virtually every project I work on with the help of artificial intelligence. It helps me - or rather, the agents - with the following.

When we reach a certain point in a task where I realize one session won't be enough, and I'll need to return to this project, repository, or task later - in that case, either at the end of the session or at the beginning (if I'm working with an existing codebase or repository), I ask the agent to write up instructions for subsequent sessions.

The purpose is to let the AI agent immediately get up to speed with the context, without having to study the project files in detail - and to save context window space and, of course, precious tokens.

Obviously, certain files within the project will still need to be referenced when necessary. But if the project is complex, it makes sense to prepare separate files that describe the document and file structure of the project, what the project is actually about, and the system architecture.

<written by a human being>

Any codebase has a README file for new contributors - they study it before starting work on a project to understand the context, and only then begin their task. Developers will get this immediately.

The same thing happens with AI agents and an agent-instructions.md file. Without it, once the session context window runs out - or whenever you want to start a new session - the agent will scan through all the files from scratch looking for what it needs, unless you explicitly tell it which file to work with and provide all the context in the initial prompt.

But why do that every time, when you can simply write all the necessary information into the agent instructions and point the agent at them each time you start a new session?

Or, if you want multiple agents working on the project in parallel, this file is exactly what makes that possible. In that case, it's worth including a workflow for handling files and commits in the instructions - to avoid conflicts.

<written by a human being>

It makes sense to include the current project progress in the agent instructions file agent-instructions.md - a step-by-step plan in to-do list format showing which steps were already completed by previous agents in previous sessions, what still remains, and which step we're on right now.

This helps work on the project in parallel without losing track, because obviously most projects don't finish the moment you start them. And it's important to sometimes just recall the context - where we left off and what stage we're currently at.

So, at the beginning of a large project, or at the end of a session with a repository, ask the AI agent to write instructions for itself, so it can start the next session by reading those very instructions.

Agent instructions should include:

1) A brief project description, to quickly understand the context of what's happening.

2) Project progress in to-do list format, to immediately pick up the current task and understand what's already been done. For large projects, this should be a link to a specific file where progress is tracked.

3) Agent behavior specifics, where you can specify the communication language for simpler interaction and faster progress.

4) Project file structure, to let the agent quickly find the right files and understand where to look under different circumstances.

5) Access instructions. For example, if the agent needs to connect to a server, specify where to find the key on the local machine, or which login and host to use.

And anything else you consider necessary - whatever your agent typically lacks when working on a task.

Before the emergence of modern AI, WordPress remained the most common choice for website development

How to Avoid Losing Context in a Complex Project When Working with AI

<written by a human being>

Imagine you're working with a large codebase. Not just some simple website, but a full-fledged application - a big system with a tangled structure, complex architecture, and multiple subsystems that interact with each other. Or you're building a system, an app, or something else entirely from scratch.

Obviously, you can't get by with a single prompt on a project like this, and there's no way to get everything done within one agent session. First, the context window won't be large enough - it keeps getting compressed, and context gets lost. Second, you might simply run out of tokens allocated for the current session, which is typical for Claude, for example. Or you just run out of time and need to come back to the project later.

One way or another, all of this calls for some kind of progress tracker. We're not reinventing the wheel here. Just like on any real-life project carried out by people, we haven't come up with anything better than a project management tool. Or, to put it simply, a task list with completion statuses. Our agents need roughly the same thing - just in a simplified form, without all the unnecessary bells and whistles that humans require to feel comfortable in this ruthless environment that forces you to work. For an AI agent, a single file that tracks this progress is enough.

How to create one and what to keep in mind - I'll cover in the next posts.

How to Avoid Losing Context in a Complex Project When Working with AI [Part 2]

<written by a human being>

Before starting a project, along with the agent instructions, ask it to create a separate progress.md file (you can read about agent instructions in previous posts).

progress.md should contain a detailed action plan and implementation roadmap for the entire project. It makes sense to create it at the very first stage, as soon as you kick off the project. Ask the AI agent to plan out everything that needs to be done within this project.

Of course, review the task list it compiled and align on it together. Make corrections if necessary, then ask the agent to format the document as an interactive (for itself) to-do list. Meaning it should contain checkboxes to mark current progress. So after the first prompt, all tasks will have empty checkboxes - no progress yet.

Going forward, the file should also include a brief description of the current stage so that the next agent in each new session can immediately get up to speed with the context. This description should cover a quick overview of the stage's tasks, what was done last, and what needs to be done right now.

AI Tip #44
Use artificial intelligence as your personal lawyer

How to Avoid Losing Context in a Complex Project When Working with AI [Part 3]

<written by a human being>

For describing the details of current progress, you can use the same progress.md document that I've been talking about in my previous posts. But if the context grows too large, or the project itself is complex - for example, developing a sophisticated information system or an application that implies multiple long working sessions over an extended period of time - it's better to move this into a separate file where you can describe the activity log in detail. In that case, you need to add a link from progress.md pointing to the log file, so that when executing specific tasks, the AI agent will open that log and update the progress there.

All of this should also be reflected in the agent instructions file agent-instructions.md, which I mentioned earlier. In other words, the agent instructions should point your AI workers to these three files:

1. the instructions file itself,
2. the progress file,
3. and the log file, if it exists separately from the progress file.

And it's essential to specify that the log must be continuously updated as tasks are completed. The workflow looks like this: a task gets done, it gets written to the log, and then marked with a checkmark in the progress file.

How to Avoid Losing Context in a Complex Project When Working with AI [Part 4]

<written by a human being>

The progress.md file, in addition to tracking project progress, should contain obstacles, difficulties, and details of the research conducted during the current session.

Very often a situation arises where an agent fails to complete a task within a single session - running into some obstacles or discovering a bug. And since the session needs to end (for example, you've run out of tokens, or the workday is simply over), it makes sense to record all the artifacts found up to that point, new knowledge gained, or - if we're hunting for a bug - all the details relevant to its potential fix.

All of this should be included either in a separate log or in the progress file progress.md itself. This doesn't really matter much, since that other file will be read when a new agent receives its context.

This way, you end up with a set of documents that any AI agent works with at the beginning and end of each session. Meaning: it comes in, reads the agent-instructions.md, the agent instructions say that project progress is tracked in progress.md, it reads the completed stages there, finds the current one, and immediately understands what it needs to do.

How to Avoid Losing Context in a Complex Project When Working with AI [Part 5]

<written by a human being>

You don't need to write everything in the prompt every time, you don't need to clarify details that might be important for the project implementation, you don't need to remember what to do next - everything will already be recorded in the progress.md plan.

All you need to do in the initiating prompt of a new session is ask the agent to read the agent-instructions.md file and proceed with the current stage.

This way, each session's prompt will be very short, everything will happen much faster and more conveniently. And, naturally, the work of the AI agents themselves will become more structured and consistent, because there is a clear algorithm of actions and a step-by-step plan to follow.

This approach also makes it possible to work on your project with several agents simultaneously. Or, for example, if you have Claude Code and Codex, and Claude Code has run out of limits for the current session, Codex can pick up and continue working right where Claude left off - which is very convenient for uninterrupted progress on the project.

So, inspired by my previous posts, for your next AI project, create an agent-instructions.md and a progress.md - and let me know how it goes.