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.

Migrating Knowledgebase With AI

<written by a human being>

The task is to migrate a knowledge base from Notion to another Notion-like tool - essentially a Notion clone, but open-source.

This can be done manually, of course, by simply copying and pasting document content from the old Notion into the new system. But being the lazy people we are, we're obviously not going that route.

Especially considering that the source knowledge base contains hundreds of documents, and transferring all of that by hand might not be back-breaking work, but it's certainly tedious, monotonous, boring, and repetitive. In short, exactly the kind of task we delegate to either code or artificial intelligence.

The first stage is fairly straightforward, because Notion has an export feature that lets you dump all documents from the current workspace into an archive, choosing the format you need: PDF or Markdown. We obviously go with Markdown, since it's well-readable by AI and, more importantly, it's the exact requirement of the new tool that will be consuming this archive.

The new service includes an import function for Notion's exported archive, because Notion is a well-known leader among this category of tools. And a system that aspires to resemble it naturally offers a migration path from the market leader - which is a pretty logical and sensible move.

Migrating Knowledgebase With AI [Part 2]

<written by a human being>

Exporting and importing using the built-in functions of Notion and the new Notion-like tool turned out to be fairly straightforward. However, after the data was migrated, I realized - with a mix of horror on one side and excitement about a new challenge on the other - that all documents ended up arranged in a simple flat structure. In other words, the nested hierarchy that existed in the original Notion knowledge base was not preserved.

The reason is that the export generated by Notion is simply a collection of documents, and it contains no information about the hierarchical relationships between them.

To preserve that structure, one would need to create a custom format - for example, a JSON file describing the hierarchy and mapping, or some other set of metadata that would tell the new system how the documents should be arranged relative to one another.

But of course, the challenge was accepted, and I started figuring out how to solve this problem with the help of artificial intelligence.

After a short review of the documentation for both systems, it turned out that they provide APIs - meaning it is possible to connect to them remotely, read and modify documents, their content, and their structure. Exactly what we need.

In other words, by writing a small program we can connect to the old knowledge base in Notion, read its structure, then connect to the new knowledge base through its API, locate the files corresponding to the Notion structure, and move them into the correct hierarchy.

As soon as the API allows all of this, the task becomes feasible for software components.

And that is exactly what we are going to do with a coding agent.

You don't need to write prompts to AI

Migrating Knowledgebase With AI [Part 3]

<written by a human being>

What should you do if your knowledge base doesn’t have an API that can be used for migration, like in my example? The system you’re working with might be closed, and you only have access through the interface.

This task is more complex, but AI can still handle it, since modern AI agents have access to browsers via plugins. For example, Claude - which I’m using to solve this problem - has a Chrome plugin and can switch between tabs, dragging files into the target system according to the structure it sees in the Notion tab.

This essentially replicates the manual work I would do if AI weren’t available. Even for AI, this kind of manual dragging takes a lot of time, because every virtual mouse movement consumes valuable tokens, and it’s still not as fast as a human.

Of course, over time this mechanism will improve and become cheaper, but for now it’s quite painful to watch it try to drag files one under another, taking about 20 seconds per action - something you can do in a fraction of a second.

So in reality, this is still a process that’s much faster to do manually, using your own cognitive and mechanical abilities.

In other words, the drag-and-dropper profession is safe for the foreseeable future.

Migrating Knowledgebase With AI [Part 4]

<written by a human being>

Let's get back to working with the API using coding agents. At this stage, all you need to do is explain the task to Claude (regular Claude chat, not Code) and ask it to write a prompt for the coding agent (Claude Code this time) - a structured task that describes all the context we've covered in the current chat, laying out all the original requirements. It's better to immediately ask the AI to save this prompt in Markdown (.md) format so it's easy for the agent to read. And to make sure nothing gets missed, all the requirements should be included in this prompt right away - API keys included.

While Claude was drafting the prompt, my job as a human meatbag was to go into Notion, open Settings -> Connections -> Develop or manage integrations -> Internal integrations -> Create a new integration -> fill out the form and hit Create. Then open the newly created integration, and in the Internal integration secret field click Show -> Copy, thereby grabbing that precious API key.

Next, I needed to go into the new system where the data from Notion will be imported, create an API key there in roughly the same way as in Notion itself. And finally, paste these keys into the prompt that was already written for Claude.

The prompt is written in MD format, and we can simply save it to a separate file from Claude chat artifact. And this is where one of the key moments in working with AI agents begins...

Oh, wow, that was unexpected...
Mom, I'm in AI now!

Migrating Knowledgebase With AI [Part 5]

<written by a human being>

For every AI project I create a separate repository. On my computer there's a dedicated folder for repositories where I keep the source code of various projects - and now I also put AI agent working files there. Even if a task doesn't involve a source code repository at all, I simply create a folder for it and point the AI agent at that folder. And it starts working right from there.

While solving the knowledge base migration task, I created exactly such a folder and dropped just one file into it - a single prompt file: that same Markdown file which, as you may recall, contains the entire structured technical specification for the task, including both API keys for both systems (Notion and the target system where the data needs to be migrated).

Now all that's needed is to launch the AI agent from this folder, and reference the corresponding file. The initial prompt in this case looks dead simple: "Read the file -filename-." After which the AI agent experiences a short circuit - kicks into high gear and gets to work.

First it checks API access. If access is confirmed, it proceeds to read the documents in Notion and in the new system via their respective APIs. Then comes the development of a Python script that will recursively walk through each document, determine its structure through one API, and then move it accordingly into the new system through the other API.

Migrating Knowledgebase With AI [Part 6]

<written by a human being>

While working on a data migration from Notion to another system, my AI agent wrote a script, then started checking whether that script could actually run by doing a cold dry-run on a small batch of documents.

Based on the results, it sent me back a list of documents that couldn't be migrated under the established algorithm - because those files had identical names. Since it was using the name as the identifier for pages and their correspondence, it couldn't figure out which one goes where.

After I gave it instructions, the work continued, and after a while the agent produced a final summary: how many documents there were originally, how many were moved, how many weren't.

In the end, all documents were successfully migrated, and the Notion structure was reproduced exactly in the new knowledge base. Everything worked great.

All in all, the entire knowledge base migration from Notion to another system took me no more than 15 minutes - including prompting the AI, the initial problem statement, and building the execution plan together with Claude.

Migrating Knowledgebase With AI [Part 7] - Finale

<written by a human being>

Wrapping up the knowledge base migration from Notion to another system - gotta say, Sonnet 4.6 handled it perfectly, no need to bring in more powerful and more expensive models (like Opus). The AI agent itself ran for just over 20 minutes, so total calendar time the task took around 40 minutes, but I personally worked on it no more than 15 minutes, everything else happened in the background. I got one question from the agent and then the final result.

If I'd done this manually, it would've taken me at least an hour and a half, maybe two hours minimum of cognitive load - two tabs open at once across two monitors, hunting down each document and dragging it under another document, trying to reproduce the structure. And I definitely would've screwed something up somewhere, missed something, forgotten something, not seen it, not been able to find it, and so on - because with that kind of monotonous work there's a tendency for attention to blur out, and it's just genuinely heavy cognitive load.

But when you do it with code, there's confidence that everything was done clean - because the algorithm doesn't make mistakes in this case: it either stops with an error, or it executes the defined sequence of actions precisely. And that's exactly the class of tasks I'm happy to delegate to AI.

Successful algorithm execution to you, and good luck working with AI!

<written by a human being>

We continue the saga of systems analysis with AI and Claude.

This time I decided to take a more comprehensive approach and do systems analysis with Claude from the ground up, from the very beginning of the modeling process. This process starts with processing all the raw materials available at the input.

When you need to produce a description of business processes, you gather artifacts - working documents, procedure descriptions, existing business process diagrams, job descriptions, all the information systems the business uses, because they're a direct representation of the objects and functions needed for various processes to operate.

For example, take a database - it contains a list of the objects that participate in business processes, and from those you can already build the first object map. And from the functions of the information system you can build the first function map.

In my case these elements hadn't been gathered yet, but what had already been gathered was a huge number of transcripts from meetings (calls) with the client in interview format - which contain the information we're looking for about the business, the processes, how everything works, who's involved, and so on.

That's actually what business process modeling in systems analysis usually starts from.

<written by a human being>

How to make AI and systems analysis work together

After the primary materials are collected, the real fun begins. You need to prepare all of this so that artificial intelligence can actually work with it.

In this case, I have no interest in using a simple chat format, because chat has a context window limited to that specific chat session - and it will get completely stuffed just from processing a single meeting transcript. These are typically multi-hour meetings that need to be held in context, and processing files like that burns through a massive number of tokens. Literally after a couple of passes, or a couple of follow-up questions in that same chat, every limit I currently have access to will be torched.

How do you avoid this?

First: for processing large volumes of materials, we won't be using chat mode - we'll be using coding mode. For Claude specifically, that's Claude Code, which you activate in the app through a dedicated Code tab. Or, if you're working through the command line - which is how I do it most of the time when I'm actually writing code - you open a terminal: PowerShell or Command Prompt on Windows.

Bottom line: if you want to process a lot of files with AI - coding mode is where you need to be.

What real things have I built with vibe-coding

<written by a human being>

When you start working with a coding agent (the most well-known ones being Claude Code or Codex) there's a key moment - you need to pick a working repository. That's the place we'll work with documents and basically any materials for the project from.

If we're building some kind of program, application, website - it's obvious to any developer that we need a repository to store the codebase, and our AI agent will work with that codebase.

But when we need to do cognitive tasks - like systems analysis tasks, for example - technically there's no repository until we actually start building an information system based on the analysis we ran. But what I'm suggesting is to flip this approach and use a repository not just as a folder for the codebase, but as a project folder that any AI agent we want to work with will operate from.

Meaning - we have a repository even when we're not writing code, just when we're working with AI. Like if we want to use it as a systems analyst, a business assistant, or whatever else - doesn't matter. For any role you assign to your agent, you need a working project.

I know this is already being done with RAG, or Retrieval Augmented Generation, but we're not gonna complicate things here - we'll just make a regular human-style repository, or just a folder with files, and point our agent at it so it can fully immerse in the context.

<written by a human being>

The very first step, even before launching Claude Code or Codex, or any other agent, is to create a folder on your computer for your project. If there's nothing in it yet, you need to fill it with files and folders first.

The moment we start talking about folders, the question of structuring that space immediately comes up - because it matters, for both any agent and any human, to know where each file lives, so you don't get lost in them, so there's a clear, strict hierarchy, and following that hierarchy is how we'll manage all the project documentation.

This is critically important, because it massively simplifies and speeds up the work. The AI doesn't need to do a contextual search through documents to figure out what's in them - which is what happens when you just dump everything into one folder. But when there's a defined structure, it helps us navigate the files ourselves, and naturally, the agents too.

You can develop this structure on your own, but if the project is complex in any way, you can also do it with the help of AI.

To do that, open Claude or ChatGPT in chat mode, pick the thinking model or one with extended thinking in reasoning mode, and describe the project to the model - if it's not already written down somewhere in text form - asking it to generate a file structure for the project.

What real things have I built with vibe-coding - Part 2

How can complex tasks be solved with the help of AI?

<written by a human being>

To do this, you need to open Claude or ChatGPT in chat mode, choose a reasoning model or a model with extended thinking capabilities, and dictate a description of the project to the model if it does not yet exist in any text format.

Yes, I intentionally used the word "dictate" here, because when we write, we usually try to write very briefly and concisely. In principle, this is the ideal approach, but with complex tasks there is often no structured workflow pattern for the project at the beginning, so I prefer simply explaining things in speaking mode. It’s easier and faster.

It doesn’t matter if I repeat some things several times. The most important part is that several paragraphs of text that I dictate will be correctly understood by the AI, because it handles context very well.

For me personally, this significantly speeds up prompting compared to typing characters, if I can simply dictate everything instead.

For dictation, you can use the built-in functionality available in some AI tools. For example, ChatGPT has this feature out of the box. Claude doesn’t have speech recognition yet, but tools like Wispr Flow can be used to dictate and instantly transcribe your speech into text.

<written by a human being>

Simple but extremely important task for you and the agent - develop a file structure for the project.

The main input for this task will be the information you give it as initial data, again, just dictate everything you know about the project. The output should be a list of folders with hierarchical nesting that needs to be created in the project folder.

A good practice is to indicate at the end of the prompt that if some details are missing, something is unclear, or there are gaps in thinking, in the project description, then preliminary clarifying questions should be asked.

You can also add that it shouldn't make stuff up and hallucinate things that weren't explicitly stated.

Then we take the specified file structure. As a rule, it'll be accompanied by some brief description of the project itself that we'll be implementing. And create folders based on this structure in our project folder.

Or, if you're really too lazy, then in this case we go into Claude Code or Codex, and launch the coding agent from the target folder and paste everything we wrote above as the initial prompt. And give the task to create the structure in this folder right away.

That's what our agent will be doing at the first stage.