Lesson 1: Introduction to Repository-Level Prompting

In the early days of generative AI, coding was done by copying and pasting single files into a web chat window. Today, AI software engineers operate directly inside your codebase. Let's explore the transition to repository-aware autonomous agents.

Single-Prompt Chat

✗ Stateless context; forgets previous files when conversation resets.
✗ Requires manual copy-pasting of code and terminal outputs.
✗ No direct filesystem, script execution, or package manager access.

Folder-Aware Agent

✓ Repository-level index maps folders, dependencies, and file systems.
✓ Autonomously scans files, writes new modules, and edits code in place.
✓ Executes shell scripts, installs packages, and runs test suites.

Theory: How Folder-Aware Agents Work

An autonomous developer agent (like Antigravity or Cline) doesn't just read your prompt. It initializes in a **workspace sandbox** containing your codebase. When you request a feature:

Workspace Discovery: The agent lists the directory structure to identify language, frameworks (e.g., Next.js, Django), and main entrypoints.
Context Indexing: It uses files like package.json or requirements.txt to understand dependencies and parses code files into Abstract Syntax Trees (AST) or embeddings to locate symbols, functions, and classes.
Tool-Enabled Loop: Rather than typing out responses, the agent runs a ReAct loop: it reads files, writes code chunks, executes compilers/tests, checks for errors, and refines its approach.

Hands-on: Structuring your Repository for AI

To make your workspace AI-friendly, you must optimize it for readability. A cluttered repository leads to model confusion, hallucinated imports, and wasted tokens. Use these design guidelines:

Standard Workspace Layout: Place source code in src/, tests in tests/ or __tests__/, and configuration files at the root level.
Strict Ignored Files: AI scan tools read files recursively. Keep folders containing generated files (e.g. .next/, build/, dist/), heavy node modules, virtual environments (venv/), and video assets (videos/) defined in your .gitignore so the agent ignores them.
Constitution Files: Add standard instruction documents like CLAUDE.md or AGENT.md. These act as custom configuration rules for agents, preventing them from modifying core libraries and ensuring styling consistency.

Concept Check

What is the primary architectural differentiator of a folder-aware autonomous developer agent compared to a stateless web chat window?

Coding Challenge: Simulating a Workspace File Indexer

Let's build a lightweight workspace file directory filter in Python! Write a function that accepts a list of file paths and filters out any paths that belong to ignored folders like .git, node_modules, and .next.

Create a function filter_workspace_paths(paths, ignored_patterns).
For each path, check if any of the ignored patterns are a substring. If not, include the path in the filtered list.
Return the filtered list.
Test it with a mock list of files (e.g. ["src/app.py", "node_modules/react/index.js", ".next/build.js", "tests/test_main.py"]) and print the output.

Write and run this simulation script in the workspace editor on the right!