What I learned from organizing an AI First project

Organizing an AI First project is not simply about using AI in more tasks. The main lesson is that AI works better when the project already has context, documentation, boundaries, acceptance criteria, and technical validation.

Context

When I started organizing brunopaim.tech, the idea was to have a simple personal website: links, projects, studies, a blog, and some behind-the-scenes notes about development, AI, and digital products.

Over time, the project also became a process lab. Not in the sense of creating a fixed methodology or a huge manual for everything. The idea was more practical: prepare the project to be understood, changed, and validated with AI support without depending only on chat memory or loose prompts.

That is the sense in which I have been using the expression AI First here. For me, in this project, AI First does not mean letting AI decide everything. It also does not mean replacing study, review, or technical judgment.

It means organizing context, documentation, and validation in a way that makes it easier to work with AI, Codex, or agents without losing traceability.

The problem with loose prompts

The problem with loose prompts is that they work well until they stop working well.

You explain a task, receive an answer, adjust something, and move on. For a small change, that can be enough. But when the project involves positioning, tone of voice, visual patterns, blog structure, SEO, approved files, specs, and validation, the conversation starts carrying too much responsibility.

• what is the right tone for the project?
• which information cannot be changed?
• which files represent approved content?
• when is a spec necessary?
• which commands validate an implementation?
• what is out of scope?
• what has already been decided?

When those answers are not in the project, AI has to guess more. And when it guesses more, the risk of drifting away from the positioning, changing what should not be changed, or implementing something too early increases.

The question that guided this process was: how can I organize a project so AI helps more, while judgment stays in the hands of the developer?

1. Project context in files

The first lesson was to move important context out of informal memory and into files in the repository.

AGENTS.md, for example, works like a kind of operational memory. It records the site goal, positioning, stack, restrictions, copywriting patterns, blog rules, and expected validations.

• the site should not look like a software house;
• the tone should be personal, technical, and accessible;
• sensitive information should not be changed without confirmation;
• posts should go through idea, outline, draft, approval, and implementation;
• relevant changes need technical validation;
• build, generate, and git status are part of closing the work.

This kind of context does not guarantee that everything will be perfect. But it greatly reduces the chance of a generic answer ignoring how the project works.

2. Documentation as living memory

Another layer was separating support documents. The brief explains what the site is. The design system preserves visual decisions. The content strategy guides the themes. The blog guidelines help keep the tone. The Spec-Driven Development documentation explains when to slow down before implementing.

In practice, this prevents every change from becoming a new decision from scratch. Good documentation, in this context, is not decoration. It is a way to reduce noise between intention and execution.

3. Specs before relevant changes

The third lesson was to use lightweight specs before changes that may affect structure, content, visuals, or positioning.

• what problem does this change solve?
• what is in scope?
• what is out of scope?
• which files will probably be affected?
• how will we know it is done?
• which validations need to happen?

This helps AI because it turns a vague intention into execution criteria. It also helps the reviewer because it makes clear whether the implementation respected the agreement.

4. Separate editorial maturity

In the blog, separating idea, outline, draft, approved content, and implementation was one of the things that organized the process the most.

• idea captures the topic;
• outline defines thesis, audience, SEO, scope, and repurposing;
• draft develops the text;
• approved content confirms tone, sensitivity, and the English version;
• implementation turns the content into site data;
• final review validates route, image, SEO, and build.

This separation makes AI more useful because it knows which maturity stage the content is in. It also makes it easier to say: it is not time to publish yet.

5. Technical validation after execution

The last point may be the most important: AI First does not remove validation.

• review the diff;
• check git status;
• run npm run build;
• run npm run generate when there is a static publication;
• validate the route in the browser when there is a visual change or new post;
• check canonical, Open Graph, and structured data in relevant posts;
• preserve out-of-scope changes.

This part is less charming than generating a screen or writing an article. But it is where the work stops being just a plausible answer and becomes a verifiable change.

A practical example

A simple example is the publication flow for posts itself. If I only asked “create an article about AI First,” I would probably get an acceptable text. Maybe even a well-written one. But it could become generic, sound like a manifesto, repeat other posts too much, or promise more than it should.

1. the idea appears in the backlog;
2. an editorial spec defines goal, scope, and out of scope;
3. the outline structures thesis, audience, SEO, safe examples, and repurposing;
4. the draft develops the text without publishing yet;
5. manual approval confirms tone, sensitivity, and the English version;
6. only then does the post enter the site;
7. the implementation goes through build, generate, route, sitemap, and structured data.

AI participates in several parts, but it does not decide on its own that something is ready. That is the point I care about most: using AI to speed up the work without dissolving the steps that give confidence to the result.

Lessons learned

• AI First, for this project, is more about organizing context than using AI for everything.
• AGENTS.md helps preserve restrictions, tone, stack, and validations across sessions.
• Documentation reduces repeated decisions and gives AI answers more consistency.
• Lightweight specs reduce ambiguity before editing files.
• Separating idea, outline, draft, approval, and implementation avoids publishing on impulse.
• Technical validation remains essential, even when the implementation looks correct.
• The more context lives in the repository, the less the project depends on the memory of a specific conversation.

Limits and caveats

This approach is still evolving. I do not think every project needs the same structure. A small experiment may work well with less documentation. A quick study may not need a spec. A simple change may be solved with a direct review.

I also do not want to turn AI First into a grand label. In the context of this site, the idea is very pragmatic: prepare the project so AI can help with more context and so changes remain reviewable.

Documentation does not solve everything. It can become outdated, incomplete, or too bureaucratic. That is why it needs to be treated as a living part of the project, not as a file nobody reads.

And of course, AI still makes mistakes. The process helps reduce that risk, not eliminate it.

Conclusion

The main lesson from organizing an AI First project is that the quality of AI-assisted work does not depend only on the model or the prompt. It depends on the environment AI enters.

When the project has explicit context, useful documentation, lightweight specs, a clear editorial flow, and technical validation, AI stops working in the dark. It starts operating within clearer boundaries.

Even then, judgment remains human. The person defines the goal, chooses the scope, approves the content, reviews the diff, runs validations, and decides whether it really makes sense for the project.

The most interesting balance is using AI to support execution and organization while keeping the process readable enough to remain in our hands.