Tutorial on creating a website using AI-Agent

Description

This article details the practical experience of developing a web project from scratch using AI agent, based on the creation of the Bitva gaming portal.

Bitva is a free online game aggregator that provides users with instant access to thousands of browser-based games without the need for downloads or registration.

Architecturally, the project was designed to be incredibly lightweight and fast, running on a pure PHP and SQLite stack without the overhead of heavy frameworks.

The main goal of this guide is to demonstrate a step-by-step algorithm for interacting with artificial intelligence, from writing the initial technical specifications to generating the final code. The methodology described here is highly versatile and will help both clients and developers build an efficient process for managing AI agents across projects of varying complexity.

Tech Stack Selection

First, it is necessary to select and approve the technologies that will be used for project development:

• Programming language (preferably with the version specified from the start)
• Framework (if required)
• DBMS (if the use of a database is required)

In the case of Bitva, which is described in this tutorial, PHP 7.2 without any frameworks and SQLite were chosen.

Human-Readable Specs

Next, it is necessary to create a specification document that is easy and convenient to navigate.

In the case of Bitva, the specification was divided into 2 parts - "Design" and "Logic and Mechanics".

Design

The "Design" section separately describes each page/element and its visual behavior.

For example, the "Design" section for Bitva describes:

• The appearance of the main page
• The appearance of Category and Tag pages
• Navigation
• The appearance of the game page

It is also necessary to create mockup images for all pages/elements. This will help both when describing the interface in text and when creating specifications for the AI Agent later.

If there are examples of interfaces from other similar websites, AI can be used to create a detailed and understandable description of the page design. If mockup images already exist at the interface description stage, they can also be provided.

In the case of Bitva, Gemini (Pro 3.1) was used to describe some interface elements (navigation, part of the main page) based on example screenshots. However, it definitely will not describe an interface perfectly from a screenshot, because it will add details that are unnecessary or incorrectly describe the actual requirements. Therefore, a specification generated by Gemini should be considered a framework that can be used as a starting point to save time, but the entire text must still be reviewed and edited manually.

Logic and Mechanics

The "Logic and Mechanics" section describes the main processes of the website. The behavior of pages and all functionality must be described in clear and understandable language.

For Bitva, the "Logic and Mechanics" section was divided into the following parts:

• Categories/Tags/Collections (complete behavior of pages and their elements)
• Game Import (logic for importing game data from supplier JSON files)
  • Supplier 1 integration
  • Supplier 2 integration
• Images (logic for saving, naming, and compressing images)
• Logic for assigning Categories and Tags

Creating the Database Schema

It is also necessary to create a database schema (or a skeleton data structure if a database is not being used).

After the specification and database schema have been approved, it is possible to proceed to creating instructions for the AI Agent.

AI Agent Instructions file

Having a clearly described specification for yourself and the team, the next step is to create an instruction file for the AI Agent. This is a .md file that will be located in the project root, and the agent will always take its contents into account during any code generation.

It is important to describe the project in as much detail as possible, clarifying all nuances that the Agent might otherwise assume or misunderstand.

It is better to write the project description in the instruction file in English so that the Agent does not have any issues understanding the language.

An LLM will be needed to create a detailed and complete description. In the case of Bitva, Gemini was used.

Asking an LLM to create such a file directly from the specification is not effective. Therefore, the process is divided into steps.

Creating the General File Framework

First, the complete specification and data structure created in the previous step should be provided to the LLM. It is necessary to explain the situation: that we are going to work with an AI Agent and need to create a .md file containing complete instructions that will be taken into account by the Agent during development. The goal is to create a description that will be perfectly understandable specifically for an AI Agent. Next, ask the LLM to write an initial file structure with draft descriptions that fully describe the project. To simplify the process, this task can be divided into two separate parts - creating the file structure for the backend first, and then separately for the frontend.

ㅤ

In the case of Bitva, the following file structure was created:

Backend:

# Project Context
## Core Philosophy
# Technical Stack
# Database Architecture & Indices
# Directory Structure
# Routing Rules
# Business Logic & Mechanics
## 1. Category & Tag Hierarchy
## 2. Game Selection Logic
## 3. Provider-Specific Integration
### Dynamic Tag & Category Resolution Algorithm
## 4. Import & Update Process (CRON)
## 5. Image Processing Pipeline
## 6. Frontend & AdBlock Mechanics
# Coding Guidelines
## 1. Security & Data Integrity
## 2. PHP Standards & Architecture
## 3. Performance & SQLite Optimization
## 4. Frontend & CSS Architecture
## 5. Code Style
# Constraints & Hard Limits

ㅤ

Frontend:

# Frontend & UI Architecture
## 1. Global Layout (layout.phtml)
## 2. Homepage View (HomeController@index)
## 3. Category & Tag Pages (`CategoryController@show` / `TagController@show`)
## 4. Navigation & Sidebar Architecture
## 5. Game Play Page (`GameController@show`)
## 6. Game Card Component (Thumbnail Anatomy)

ㅤ

Filling the Sections of the Instruction File

First, it is best to work on the backend separately and move to the frontend afterward.

At this stage, it is necessary to:

• Once again provide the LLM with the complete specification that we originally created for ourselves (to refresh its context), along with the generated backend sections.
• Ask the LLM to fill all backend sections in as much detail as possible (in English), using our specification as the primary source (the full specification is provided because frontend details may affect backend formulations).
• Place emphasis on the fact that the descriptions must be written specifically so that an AI Agent can understand the instructions as clearly and transparently as possible, leaving no room for assumptions or creativity that could lead development in a direction different from what is intended.

As a result, we will obtain a reasonably well-described backend section, which will become the foundation for further development.

The generated result must be reviewed very carefully and thoughtfully, because some parts will inevitably be described differently from what is actually required, while many functions will be described with insufficient detail.

This happens because our original specification, written for people, does not contain many details that seem "obvious" to us and would only overload human perception, but for an AI Agent these are critically important nuances. Without them, the Agent will begin making its own assumptions.

All necessary corrections, additions, and clarifications should be communicated to the LLM, and it should be asked to update the relevant subsections so that the AI Agent has no unanswered questions and the text contains no inaccuracies that could mislead it or force it to make assumptions.

As a result, the amount of text will increase significantly because many additional details and clarifications required for the Agent's precise understanding of the project will be added.

After generating what appears to be a good backend section, work begins on each of its individual subsections.

ㅤ

Working with Individual Sections of the Instruction File

Now it is necessary to perform a very long and detailed process of reviewing and refining all details of each instruction subsection.

Step 1: Initial Subsection Review. First, we provide our LLM with the first backend subsection and the corresponding part of our specification (the one written for humans, if such a subsection exists in our specification). The request will look like:

Now check specifically the subsection (subsection name) for formulations that an AI Agent might misinterpret, ambiguities, hidden bugs in our description, missing necessary clarifications for the AI Agent, and fix them

As a result, a large number of nuances and hidden bugs will inevitably be discovered. The LLM will correct them and claim that the result is now an excellent reference version of the subsection. However, such statements must never be trusted. After receiving this revised version of the subsection, it must be reviewed manually. If corrections are needed, we must explain to the LLM what is wrong and ask it to specify exact lines or formulations that need to be replaced or corrected.

Important: From this moment on, we no longer copy the full version of the section from the LLM chat. Instead, we must request only the specific lines that need to be changed or added in .md format so they can be copied directly. Otherwise, the LLM may start shortening previous formulations while adding new clarifications.

Step 2: Deep Review "from the Agent's Perspective". Next, we again provide the final version of the subsection to the LLM with a request like:

Check the final version of our subsection again for formulations that an AI Agent might misinterpret, ambiguities, hidden bugs in our description, missing necessary clarifications for the AI Agent, or any other issues.

*Send the current version of the subsection for review*

To make the LLM more effective at finding vulnerabilities, we can assign it a role during review, for example:

Read this subsection as a 'lazy' or overly literal AI agent that looks for any opportunity to simplify implementation. Find loopholes where it could make mistakes or do something unintended, and close them

It will almost certainly find 2–3 critical issues that could cause hallucinations or bugs in the Agent's output. If it responds with the full subsection again or provides corrections in plain text instead of structured changes:

• It must be reminded that it should only provide lines to replace or append, formatted in .md so they can be copied directly.
• You may even paste its previous incorrect response and ask it to rewrite it properly.

Step 3: Iterative Reviews. After applying these 2–3 rounds of corrections, the LLM will again claim the result is perfect. However, this should still not be trusted. The full subsection must be reviewed again with the same request:

Check the final version of our subsection again for formulations that an AI Agent might misinterpret, ambiguities, hidden bugs in our description, missing necessary clarifications for the AI Agent, or any other issues. Read this subsection as a 'lazy' or overly literal AI agent that looks for any opportunity to simplify implementation. Find loopholes where it could make mistakes or do something unintended, and close them.

*Send the current version of the subsection for review*

There is a 99% chance that 2–3 vulnerabilities or unclear formulations will still be found.

This process of "request review => apply fixes => request review" must be repeated until the LLM stops finding problems. Initially, critical vulnerabilities will be found, then potentially buggy formulations, then missing clarifications to prevent the agent from making assumptions, and finally minor cosmetic issues.

It is very important to carefully read the LLM's explanations of the problems rather than blindly copying suggested replacements. Sometimes the LLM suggests optimizations or features that are unnecessary and should be rejected.

This process may take 10, 20, or even more iterations, depending on the complexity of the subsection. However, after eliminating the final minor issues, the LLM will eventually state that the description is perfect and no further improvements can be made. We ourselves see the progress of corrections (serious problems have long ceased to be found, and the last ones were very minor edits that simply bring the instructions to perfection), so such an answer in this context can be trusted.

This process must be applied to every subsection. It is time-consuming and token-intensive, but it results in a highly detailed and precise description required for the AI Agent.

Step 4: Full Section Analysis (Backend). Once all subsections of the backend are brought to a conditional ideal, it is necessary to give LLM a complete picture of all subsections of the backend with a request:

Now carefully analyze the full backend structure and check whether there are any inconsistencies, contradictions, or new issues that appear in the combined context

It is possible that the LLM will find additional issues that only appear when viewing the system as a whole. While these are unlikely to be critical (since the model remembers previous subsections), they can still occur, and it is better to be safe. If issues are found, the same iterative correction process must be applied again until no problems remain.

As a result, we obtain a highly detailed and precise backend section (an ideal specification for the AI Agent).

Step 5: Creating and Validating the Frontend Section. Next, following the same approach used for the backend section, we create the frontend section. We already have subsection names with minimal descriptions from previous steps, so the same process is applied: generate the filled frontend section based on the human specification and subsection outline, then iteratively review, refine, and validate each subsection until it reaches an ideal state, ensuring consistency across all parts.

Frontend subsections require even more iteration than backend ones because algorithms and rules are easier for an AI Agent to interpret than visual design and UI behavior, which can be implemented in multiple ways (and may, for example, break SEO). Therefore, frontend subsections will be much more detailed due to the large number of constraints introduced to prevent broken SEO, poor mobile responsiveness, or faulty JavaScript behavior.

Special attention must be paid to the principle of a single source of truth. For example, media queries and screen breakpoints for mobile and desktop layouts must be defined at the very beginning of the document as global constants (e.g., strictly < 1025px for mobile and >= 1025px for desktop). If this value is not fixed at the beginning, the Agent may define different values in different sections, leading to a completely broken responsive design.

Step 6: Final Comprehensive Document Validation. After finalizing both backend and frontend sections, the full document must be validated as a whole. Similar to subsection validation, the entire file containing both frontend and backend must be reviewed for inconsistencies across sections. If necessary, specific lines are corrected and the document is revalidated until no issues remain.

Stage Outcome:

As a result, we obtain a high-quality instruction file (.md) for the AI Agent that will guide it throughout the entire development process. The Agent must still be reminded of these rules when generating functionality, as such a large file cannot be fully accounted for in every request. However, the key achievement is that we now have a maximally detailed and precise specification tailored for an AI Agent.

AI-Assisted Development

After creating a clear and detailed instruction file for the AI agent, you can proceed to generating the project code.

The following describes the development experience of Bitva.com, but it is applicable to the development of most systems.

Step 1: Agent Launch and Basic Generation. A project folder was created, and the instruction file (created in the previous steps) was placed in the root, along with prepared configurations. The agent was launched in the project directory, and generation was started with the prompt:

read the instructions.md file and execute its instructions

The agent analyzed the instructions.md file and asked what exactly I wanted it to do, providing examples — full project initialization, import, frontend, pages, configuration. The option of full project initialization was chosen — prompt to the agent:

Perform full project initialization

After that, it spent about 5–10 minutes creating the basic website functionality according to the instructions from the instructions.md file. The agent reported that the work was completed and said that the site could now be launched and tested.

Important note: It is important to remember that if we initially specify that index.php should be in the public folder, the agent will follow that structure, and the server must be started with the appropriate parameters.

From the very first launch, the site worked (although not perfectly, but it did not crash with an error, which is encouraging).

Step 2: Creating the AGENTS.md Cheat Sheet and Code Commits. Next, you need to ask the agent to create an AGENTS.md file in the project root so that it can refer to it as a constant prompt regarding the main nuances of the site. Thus, there end up being 2 files with the project description in the project root:

• instructions.md — our huge and maximally detailed file (we will refer to its sections during tweaks and edits).
• AGENTS.md — the compact (relative to instructions.md) file, in which the agent has collected the most important details for itself that it needs to remember when executing any request.

It is necessary to create a repository and commit the obtained result. And subsequently, every change made by the Agent must be committed.

Step 3: Audit and Refactoring. After that, you need to change the model (in the case of Bitva, DeepSeek was chosen) and request a recheck and optimization of the generated code. Prompt:

Analyze the project once again and fix all problems

It will perform refactoring and improvements across many files.

In the Bitva project, the main functionality that needed to be tested first was the import of game data and images from provider sources, so the next step was a request for a detailed audit of the game import functionality code and checking it against our instructions. The agent found a minor bug with game naming, fixed it, and reported that everything now strictly corresponds to the instructions. It provided the command to run the import so that the functionality could be tested.

Step 4: Debugging (Separating the Roles of LLM and Agent). After the first run of the game import, several bugs were discovered, and now the main assistant becomes not the agent, but our LLM, with which the instructions file was compiled.

To eliminate minor bugs, it is easier to use the LLM (when it is also in the context of the project), so as:

• not to spend the Agent's tokens;
• not to confuse its context with attempts to solve bugs;
• and not to risk that upon a requested minor fix it might start editing other working project files.

For a minor fix, it is enough to give the LLM the function code (or the whole class, if necessary), describe the problem, and it is advisable to ask whether the solution to this bug is simple and fast and we can solve it ourselves, or if it will require sending a request to the agent. If the bug is minor, the LLM points it out very quickly and tells you what needs to be fixed (most often it is either the Agent's inattention or partially missing specific data).

For example, the first bug found on Bitva was an incorrectly specified field name in the game provider's JSON, which suited the first provider but did not suit the second, so images from the second provider did not load. If we had told the Agent that the image import from the second provider was not working, it would have started analyzing and modifying the working code (with just one incorrectly specified field name), adding the handling of exceptions that are unrealistic in our case, wasting tokens in the process and confusing its context. But the LLM immediately said that the field name was specified incorrectly, since we compiled the instructions file with it and it was provided with JSON examples from the providers (examples were not included in the instructions file; field names were specified, but apparently the agent perceived them insufficiently accurately, since there were no examples that would overload the instructions file).

In general, it can be said about this that:

• it is much better to search for and fix minor bugs, discuss and reason about the project with the LLM, the LLM's context can be loaded with examples and assumptions.
• And it is best to give the AI Agent clear prompts for development, without reasoning and inaccuracies. It copes perfectly with development according to instructions.

Next comes the stage of tweaks and further improvements of the project.

Stage of tweaks and improvements of the project

Most likely, the first generated version (even after fixing bugs) will be incomplete, or major edits will be required. In this case, you need to turn to our LLM, clearly and in detail describe the improvement, and ask whether it is necessary to involve the Agent for this, or if it can be done simply and quickly without its participation.

If the edit is indeed major (requires understanding the logic and connection between several files), then the LLM will say that it will be more efficient to pass it to the Agent. In this case, it is necessary to ask the LLM to generate a prompt for the Agent:

Generate a clear and understandable prompt for the AI Agent so that it implements my improvements. Write in such a way that even a lazy agent will understand everything, take it into account, and implement it. Also refer to the instructions.md file in the project root. For better understanding, here is the section of the instructions file that relates to the improvements:

*send the section of the instructions file that specifically relates to the improvements we want to make*

The LLM will generate a clear and understandable prompt for the Agent, which will describe in maximum detail exactly what we need to do. Usually, it takes from 5 to 20 lines, so:

• it is necessary to create a file where we will copy and edit all prompts to the Agent before sending.
• You need to copy the generated prompt from the LLM into the prompt editing file, reread it, and if necessary - edit it.
• Only after this can you copy the ready prompt and paste it into the agent's input field (in the case of opencode, a short message [N lines pasted] will be displayed in the input line, which means everything was pasted correctly).

Important: Such manipulations are necessary so that in case of editing a large prompt directly in the agent's input line, you do not accidentally send an incomplete prompt and thereby clog the Agent's context with incorrect data. Such manipulations must be performed during every major improvement that requires the Agent's participation.

The need for major edits/improvements

In the case when the technical specifications are changed or significantly supplemented during the development process, it is necessary to edit both the instructions.md file and AGENTS.md, otherwise, the Agent may in a few steps start returning the version of the functionality described in these files, or mix it with the new one.

In such a situation, at the stage when we ask the LLM whether we will need to ask the Agent to perform the necessary edits/improvements, the next request should not be to generate a prompt for the Agent, but a re-analysis and editing of the instructions file.

You need to send the LLM the old version of the section that describes the part of the project that needs to be changed/improved, and ask it to point out specifically and write in .md format (so that we can simply copy the new lines) what needs to be changed/added so that the instructions exactly match the new requirements. The prompt will be approximately like this:

*detailed description of the new requirements*

Write exactly what specifically needs to be replaced or added in the old version of the instructions block so that it exactly matches the new requirements. Write in .md format so that the lines can be easily copied. Write in detail and understandably for the AI Agent. Here is the old version of the block from the instructions file that needs to be edited:

*old version of the block from the instructions file that needs to be edited*

If the new requirements affect several sections of the instructions file, then it is better to edit them separately so that the LLM does not have to work with a huge text all at once.

The LLM will output what exactly needs to be replaced/supplemented in the instructions section.

• You need to carefully read the edits, analyze them yourself, and see if there are any inconsistencies with our goal or contradictions with the rest of the functionality. It may be necessary to make edits.
• If the changes are global, you need to run the edited section through the LLM a few more times to clear the new version of possible bugs or inaccuracies (using the same scheme by which we initially generated and edited this file).
• After the entire instructions.md file completely matches the new requirements, it is necessary to make edits to the AGENTS.md file (it is much smaller, so no difficulties should arise), after which you can generate a prompt for the Agent.
• Now we give the LLM the section/sections that we have just edited with it, and act according to the known scheme from the Stage of tweaks and improvements of the project.

Conclusions

• The Agent copes perfectly with the development of the project according to clear instructions, so do not hesitate to invest time in a detailed description of the instructions.md file and in generating voluminous and maximally detailed prompts for the Agent. Only in this case will it create exactly what we need.
• The LLM handles minor bugs and improvements perfectly, so if you need to try something, test it, or make minor edits, it is best to use the LLM specifically for such tasks.