Guide: Developing Quality Software Assisted by AI Agents

This guide is an improved version of the proposal initially presented in "Extended Context. Agents also need to take notes".

Its purpose is to implement a strategy that allows us to develop complex projects assisted by agents without losing the coherence and quality of the generated code.

Its writing is oriented for use with tools like Cursor or GitHub Copilot, but it can be easily adapted to many others.

Context System Structure

To implement this strategy, we create a context/ folder in the project root with the following structure:

context/
├── 01-expert.md      # Synthetic expert definition
├── 02-analysis.md    # Analysis of existing code (empty)
├── 03-plan.md        # Master development plan (empty)
└── 04-backlog.md     # Detailed tasks and their status (empty)

Step 1: Synthetic Expert Definition

The first step consists of defining a "synthetic expert": a specific role with clear competencies and restrictions that will guide the AI agent throughout development.

Prompt for the agent:

Read the `context/01-expert.md` file to understand your role in the project.

Do not generate code until you receive specific requirements.

Example content for context/01-expert.md:

# SUDO: Act as a Senior Frontend Development Expert specialized in HTML5, CSS3/SCSS and JavaScript ES6+.

## ROLE
Senior Frontend Developer (10+ years) expert in semantic HTML5, advanced CSS3/SCSS with BEM and ITCSS methodologies, and modern JavaScript ES6+, with focus on component architecture, performance and accessibility.

## TECHNICAL_COMPETENCIES

- Semantic HTML5 and accessibility (ARIA, WCAG 2.1)
- Advanced CSS3 (Grid, Flexbox, animations, custom properties)
- SCSS/Sass with ITCSS architecture (Inverted Triangle CSS)
- Strict BEM methodology (Block__Element--Modifier)
- JavaScript ES6+ (async/await, modules, destructuring, classes)
- State management and component architecture
- Web performance optimization (Core Web Vitals)
- Unit and integration testing
- Modern build tools (Vite, Webpack)

## WORK_PRINCIPLES

- Clean and maintainable code following SOLID principles
- Clear and concise documentation
- Mobile-first and responsive approach
- Progressive enhancement
- Semantics before presentation

## RESTRICTIONS

- Avoid jQuery and legacy libraries unless specific requirement
- Maintain compatibility with modern browsers (latest 2 versions)
- Prioritize native solutions over external dependencies
- Do not generate code until receiving specific requirements

⚠️ Important: The last restriction ("Do not generate code until receiving specific requirements") is fundamental, models are very proactive 😅

Step 2: Project Code Analysis

This step is only necessary for existing projects. If you're starting a project from scratch, you can omit it.

Now we ask the agent to analyze the project code and save its analysis in context/02-analysis.md

Prompt for the agent:

Analyze in depth the current project code. Exclude the `context/` folder from the analysis.

Save the analysis result in `context/02-analysis.md` with the following structure:
- Executive summary
- Current architecture
- Technologies used
- Identified patterns
- Potential improvement areas
- Critical dependencies

When finished, wait for additional instructions without performing any action.

⚠️ Important: Don't hesitate to iterate with the agent if you're not satisfied with their first analysis.

Step 3: Master Plan Creation

Once the code is analyzed, we explain to the agent what we want to develop and ask them to define a master plan that should be saved in context/03-plan.md

The master plan is the fundamental document that will guide all development. Take the time necessary to clearly define requirements and objectives.

Prompt for the agent:

Based on the following requirements, create a detailed master plan for development:

[PROJECT REQUIREMENTS]

I need to create a REST service that processes images in batches. The service must:

- Receive multiple images in a single request
- Resize images according to configurable parameters
- Compress and optimize for web
- Return processed images in WebP format
- Implement cache to optimize resources
- Provide endpoints to query processing status

Technical considerations:

- Use Bun for its performance in intensive operations
- Evaluate compatibility with image processing libraries
- Implement asynchronous processing for large batches
- Include robust input validation

[END OF REQUIREMENTS]

Create a structured master plan and save it in `context/03-plan.md`.

When finished, wait for additional instructions.

⚠️ Important: Continue dialoguing with the agent if you see that the plan is missing or has too much.

Step 4: Detailed Backlog Creation

At this point we ask the agent to transform the master plan into executable tasks, as small and specific as possible. More granular tasks result in higher quality code.

Prompt for the agent:

Divide the master plan into atomic tasks following these criteria:

- Detailed description of technical requirements
- Clearly identified dependencies

Save the list in `context/04-backlog.md` with this structure:

# Task Backlog - [Project Name]

## Project Summary
[Brief description and implementation of the plan in `context/03-plan.md`]

## Task Status

### PHASE 1: [PHASE TITLE]

- **1.1** ⏳ [task title]
  - **Detailed description**:
  - **Dependencies**:
  - **Date**: 
  - **Work completed**: 

- **1.2** ⏳ [task title]
  - **Detailed description**:
  - **Dependencies**:
  - **Date**: 
  - **Work completed**:

### PHASE 2: [PHASE TITLE]
[Continue with the same format...]

## Status Legend
- ⏳ Pending
- 🔄 In progress
- ✅ Completed
- ⚠️ Blocked

## Notes and Dependencies
[Additional relevant information]

## Progress Tracking
- Total tasks: 0
- Completed tasks: 0
- Progress: 0%

When finished, wait for additional instructions

⚠️ Important: It's necessary to indicate to the LLM the backlog structure we want, otherwise it gets creative 😬

Step 5: Task Execution

With the backlog defined, we proceed to execute tasks systematically.

Prompt to execute a task:

Execute task 1.1 from the backlog (`context/04-backlog.md`) following its description strictly.

Additional context available in:
- `context/02-analysis.md` (if exists)
- `context/03-plan.md`

Execution requirements:
- Use agent tools to create files and folders (not terminal)
- Follow conventions established in the initial prompt
- Document code according to defined standards
- Do not perform actions outside the task scope

Upon completion:
1. Update task status in `context/04-backlog.md`:
   - Change status to ✅
   - Add completion date
   - Describe work completed
   - Update Progress Tracking
2. Wait for additional instructions without executing more tasks

⚠️ Important: It's necessary to ask the LLM not to do anything more than indicated in the task to avoid overstepping.

Step 6: Context Window Reset

To maintain quality and coherence, it's necessary to periodically reset the context window.

It's evident that we should reset the context window when we notice the agent starts to "lose direction". But the optimal approach is to never reach this point and open a new chat:

• Every 4-6 completed tasks
• When changing phases (our backlog example is structured in phases that are divided into tasks).

Reset prompt:

Initial instructions:

1. Read `context/01-expert.md` to understand your role in this project
2. Read `context/02-analysis.md` to know the current state of the code
3. Read `context/03-plan.md` to understand the objectives
4. Read `context/04-backlog.md` to see progress and pending tasks

Provide a brief summary of:

- Your role and competencies
- Current project status
- Next tasks to execute

When finished, wait for additional instructions.

Automation with Shortcuts

Both GitHub Copilot and Cursor allow creating custom shortcuts for frequent prompts:

GitHub Copilot

• Instructions
• Prompts

Cursor

• Rules

System Benefits

This context management strategy transforms the context window limitation from an obstacle into an opportunity to work more structured and efficiently. The main benefits include:

• Continuity: Maintain progress without losing critical information
• Consistent quality: The agent maintains the same level of detail and precision
• Traceability: Complete record of decisions and project evolution
• Better collaboration: Facilitates team work and onboarding of new members

Conclusion

By implementing this system, you not only avoid the technical limitations of LLMs but also establish a more professional and scalable development methodology for AI-assisted projects.

---

Questions or suggestions? Share your experience implementing this strategy and help improve the guide for the community.