Lesson 2: AI assisted IDEs landscape

⤵️ Quick shortcut: Select the module you’re currently studying ⤵️

📖 Lesson 2: Documentation - First and Vibe Coding (for Flow)

Key Topics

Documentation-First:
- Generating the structure or specification of a feature (endpoints, classes, functions) before coding.
- How having a prior outline helps the AI produce more accurate suggestions.
Vibe Coding:
- A more fluid, co-creative development style with AI, where you don’t have rigid specs but iterate rapidly.
- Real-world examples: quick prototypes of microservices or functions in an “exploratory” mode.

Below you will find some suggested materials on these topics, which we believe may help you complete the final activity in the lesson. Please note that using these resources is entirely optional, and you are welcome to explore any other sources or courses at your own discretion.

Here are some recommended courses to explore:

Key Topics

Documentation-First:
- Generating the structure or specification of a feature (endpoints, classes, functions) before coding.
- How having a prior outline helps the AI produce more accurate suggestions.

Markdown Guide

Comprehensive but easy-to-read reference on creating structured documentation.

Perfect for quickly outlining specs before handing them off to an AI tool.

To Read

OpenAPI Specification (Swagger) Docs

Official site for defining RESTful endpoints in a standardized format.

Shows how to create endpoint definitions that AI can use to generate boilerplate code.

To Read

Documentation-Driven Development

How to rapidly complete a full database-driven user story using documentation-driven development (DocDD). In this step-by-step walkthrough, you’ll see exactly how DocDD streamlines the dev process—from requirements to deployment—saving time and reducing errors

Go to the Course

Key Topics

2. Vibe Coding:

- A more fluid, co-creative development style with AI, where you don’t have rigid specs but iterate rapidly.
- Real-world examples: quick prototypes of microservices or functions in an “exploratory” mode.

Cursor Course: FullStack development with Cursor Vibe Coding

Vibe Coding, Learn to build Micro SAAS from the ground up using Cursor (Includes v0, shadcn UI, Vercel Deployment)

Go to the Course

Vibe Coding Is The Future

Andrej Karpathy recently coined the term “vibe coding” to describe how LLMs are getting so good that devs can simply “give in to the vibes, embrace exponentials, and forget that the code even exists.” We dive into this new way of programming and what it means for builders in the age of AI.

Go to the Course

Vibe Coding Complete Tutorial and Tips -Curso/Windsurf

The video introduces “vibe coding” using AI tools like Cursor and Windsurf to accelerate software development.

It walks through setup, key features like AI code completion, and how to guide the AI effectively.

Tips include being clear with instructions and staying involved to get accurate, useful results.

Go to the Course

🙌 Hands-On

Activity:
1. Write a short Markdown document describing a new functionality (e.g., an endpoint for user management).
2. Use a code assistant to generate the skeleton of that functionality based on your doc.
3. Then “vibe” a bit—add or modify features freely while the AI suggests improvements.
Goal:

Experiment with the contrast between having a clear doc first (documentation-first) vs. a more ad-hoc approach (vibe coding).

Lesson 2: Documentation-First and Vibe Coding (Assignment)

Assignment (With More Coding!)

Create two endpoints in the same project, each using a different approach:
- Endpoint A (Documentation-First):
  - Write out the endpoint’s signature, parameters, and expected response in a Markdown file (e.g., /api/users returning a paginated list).
  - Use your code assistant to generate the skeleton from the documentation.
- Endpoint B (Vibe Coding):
  - Without any prior doc, start “conversing” with the assistant in your IDE to suggest the endpoint structure.
  - Tweak it on the fly, adding validations or changes as you see fit.
Submit both endpoints in a repo or folder, along with a README:
- Share your experience with each approach (which felt faster or more natural?).
- List any improvements you’d like to see from the AI in each method.

Objective
Practically apply both methodologies (documentation-first and vibe coding). Compare how the code or the coding experience differs depending on whether you rely on a prior spec or you free-form with AI.

Step-by-Step Instructions

Set Up or Reuse a Project
- If you already have a small Node.js/Express or Python/Flask project from Module 1, Lesson 1, you can extend it.
- Otherwise, create a new folder or project – for example, a Node.js app with an app.js or server.js file, plus a minimal package.json.
Create a Markdown File for Documentation-First (Endpoint A)
- Make a file named ENDPOINT_A_SPEC.md in your project.

Outline the details of the endpoint. For example:
markdown
CopiarEditar
# Endpoint A: /api/users (Documentation-First)

**Method**: GET

**Query Params**:

- `page` (integer, optional, default=1)

- `limit` (integer, optional, default=10)

**Response**:

- JSON array of users, paginated

- `totalCount` field indicating total users

Include any validations, expected status codes, or example responses if relevant.

Generate Endpoint A Using Documentation-First
- Open your IDE and reference ENDPOINT_A_SPEC.md.

Start coding or comment the doc inside your code, e.g.:
javascript
CopiarEditar
// According to ENDPOINT_A_SPEC.md, we need a GET /api/users

// with optional page & limit, returning paginated users + totalCount.

Let your code assistant propose a skeleton. If it doesn’t automatically, prompt it:
javascript
CopiarEditar
// "Generate an Express GET /api/users route with page & limit, reading from request query."

Accept or refine the suggestions. For example, you might end up with:
javascript
CopiarEditar
app.get('/api/users', (req, res) => {

const page = parseInt(req.query.page) || 1;

const limit = parseInt(req.query.limit) || 10;

// sample data or database logic

// ...

});

Test it quickly (e.g., curl http://localhost:3000/api/users).

Create Endpoint B (Vibe Coding)
- This time, no doc. Don’t outline it in Markdown. Just spontaneously “chat” with your code assistant in code comments.

For example:
javascript
CopiarEditar
// I'd like a POST /api/users to create a new user, but let's do it vibe-style:

// Start from an empty route and let the AI fill details.

Start typing:
javascript
CopiarEditar
app.post('/api/users', (req, res) => {

// ...

});

Pause to see if your AI suggests validation, data structures, or DB logic. If not, prompt it with short instructions:
javascript
CopiarEditar
// "We need to handle user creation with name/email, return 201 Created."

Tweak or accept the suggestions. Add validations or error responses spontaneously, as you “feel” the code’s direction. That’s the essence of vibe coding.

Compare Approaches
- In your IDE or a note, reflect on each approach:
  - Did the documentation-first approach produce more consistent code or require fewer clarifications?
  - Was vibe coding faster or more “creative,” but sometimes needed more corrections?
- If you want, run quick tests for both endpoints to confirm they work.
Submit Both Endpoints & README
- Place your final endpoints in a folder or push to a repo.

In your README.md (or a separate doc):
markdown
CopiarEditar
# Comparison of Documentation-First vs. Vibe Coding

**Endpoint A**: /api/users (GET)

- Created using documentation-first approach.

- Observations: [Write a sentence or two about how it went.]

**Endpoint B**: /api/users (POST)

- Created using vibe coding approach.

- Observations: [Which felt faster, or what extra clarifications did you need?]

**Improvements for the AI**:

- Maybe the assistant lacked clarity on certain error handling...

- Or it repeated code suggestions...

Wrap Up
- You’ve practically applied both a documentation-first approach (structured spec) and a vibe coding approach (freeform conversation) for two separate endpoints.

This side-by-side comparison reveals how each method influences code generation speed, accuracy, and overall experience with your AI assistant.

🗒️ Activity:

Create two endpoints in the same project, each using a different approach:
1. Endpoint A (Documentation-First):
  1. Write out the endpoint’s signature, parameters, and expected response in a Markdown file (e.g., /api/users returning a paginated list).
  2. Use your code assistant to generate the skeleton from the documentation.
2. Endpoint B (Vibe Coding):
  1. Without any prior doc, start “conversing” with the assistant in your IDE to suggest the endpoint structure.
  2. Tweak it on the fly, adding validations or changes as you see fit.
Submit both endpoints in a repo or folder, along with a README:
1. Share your experience with each approach (which felt faster or more natural?).
2. List any improvements you’d like to see from the AI in each method.
Objective: Practically apply both methodologies. Compare how the code or the coding experience differs depending on whether you rely on a prior spec or you free-form with AI.

Lesson 2: Documentation-First and Vibe Coding (Assignment)

Assignment (With More Coding!)

Create two endpoints in the same project, each using a different approach:
- Endpoint A (Documentation-First):
  - Write out the endpoint’s signature, parameters, and expected response in a Markdown file (e.g., /api/users returning a paginated list).
  - Use your code assistant to generate the skeleton from the documentation.
- Endpoint B (Vibe Coding):
  - Without any prior doc, start “conversing” with the assistant in your IDE to suggest the endpoint structure.
  - Tweak it on the fly, adding validations or changes as you see fit.
Submit both endpoints in a repo or folder, along with a README:
- Share your experience with each approach (which felt faster or more natural?).
- List any improvements you’d like to see from the AI in each method.

Step-by-Step Instructions

Set Up or Reuse a Project
- If you already have a small Node.js/Express or Python/Flask project from Module 1, Lesson 1, you can extend it.
- Otherwise, create a new folder or project – for example, a Node.js app with an app.js or server.js file, plus a minimal package.json.
Create a Markdown File for Documentation-First (Endpoint A)
- Make a file named ENDPOINT_A_SPEC.md in your project.

Outline the details of the endpoint. For example:
markdown
CopiarEditar
# Endpoint A: /api/users (Documentation-First)

**Method**: GET

**Query Params**:

- `page` (integer, optional, default=1)

- `limit` (integer, optional, default=10)

**Response**:

- JSON array of users, paginated

- `totalCount` field indicating total users

Include any validations, expected status codes, or example responses if relevant.

Generate Endpoint A Using Documentation-First
- Open your IDE and reference ENDPOINT_A_SPEC.md.

Start coding or comment the doc inside your code, e.g.:
javascript
CopiarEditar
// According to ENDPOINT_A_SPEC.md, we need a GET /api/users

// with optional page & limit, returning paginated users + totalCount.

Accept or refine the suggestions. For example, you might end up with:
javascript
CopiarEditar
app.get('/api/users', (req, res) => {

const page = parseInt(req.query.page) || 1;

const limit = parseInt(req.query.limit) || 10;

// sample data or database logic

// ...

});

Test it quickly (e.g., curl http://localhost:3000/api/users).

Create Endpoint B (Vibe Coding)
- This time, no doc. Don’t outline it in Markdown. Just spontaneously “chat” with your code assistant in code comments.

For example:
javascript
CopiarEditar
// I'd like a POST /api/users to create a new user, but let's do it vibe-style:

// Start from an empty route and let the AI fill details.

Start typing:
javascript
CopiarEditar
app.post('/api/users', (req, res) => {

// ...

});

Tweak or accept the suggestions. Add validations or error responses spontaneously, as you “feel” the code’s direction. That’s the essence of vibe coding.

Compare Approaches
- In your IDE or a note, reflect on each approach:
  - Did the documentation-first approach produce more consistent code or require fewer clarifications?
  - Was vibe coding faster or more “creative,” but sometimes needed more corrections?
- If you want, run quick tests for both endpoints to confirm they work.
Submit Both Endpoints & README
- Place your final endpoints in a folder or push to a repo.

In your README.md (or a separate doc):
markdown
CopiarEditar
# Comparison of Documentation-First vs. Vibe Coding

**Endpoint A**: /api/users (GET)

- Created using documentation-first approach.

- Observations: [Write a sentence or two about how it went.]

**Endpoint B**: /api/users (POST)

- Created using vibe coding approach.

- Observations: [Which felt faster, or what extra clarifications did you need?]

**Improvements for the AI**:

- Maybe the assistant lacked clarity on certain error handling...

- Or it repeated code suggestions...

Wrap Up
- You’ve practically applied both a documentation-first approach (structured spec) and a vibe coding approach (freeform conversation) for two separate endpoints.

This side-by-side comparison reveals how each method influences code generation speed, accuracy, and overall experience with your AI assistant.

Back

Page updated

Report abuse