Vibe Engineering Effect Apps — Michael Arnaldi, Effectful

The Core Problem: Outdated Knowledge in LLMs

Large Language Models (LLMs) are powerful but have fundamental limitations that hinder their effectiveness as coding agents. Unlike human brains, they don’t learn continuously. Their knowledge is frozen at the time of their last training, which can be months out of date. This means they are often unaware of the latest library versions, APIs, or best practices.

The context window, which is the model’s short-term memory, is a fixed-size array. While models with million-token context windows exist, feeding them excessive information can lead to confusion and degraded performance. The key insight is that coding agents have been primarily trained to consume and produce code, not to read human-written documentation or use external tools they haven’t seen before.

The Solution: “Just Clone the Repo”

The most effective strategy to make an agent proficient with an unfamiliar or undocumented library is to give it direct access to the library’s source code. The proposed workflow is simple but powerful: “just clone the repo.”

By cloning a library like Effect into the project’s directory (e.g., in a .repos folder as a git subtree), you masquerade the library’s code as part of your own codebase. This leverages the agent’s core training, which is to analyze, understand, and replicate patterns within the local project files.

This approach is superior to relying on code in node_modules or files in .gitignore, as agents are often explicitly trained to de-prioritize or ignore these locations.

Practical Workshop: Building a Type-Safe API with an Agent

The session demonstrated this strategy by building a full application from an empty repository.

1. Project Setup and Creating a “Back-Pressure Loop”

The first step was to establish a strict environment to guide the agent and prevent common errors. This “back-pressure loop” is crucial for ensuring code quality.

• Initialization: The agent was instructed to set up a new project using Bun, Vitest for testing, and TypeScript.
• Strict Diagnostics: A critical step was configuring the tsconfig.json to treat all diagnostics—even suggestions and warnings—as errors. This forces the LLM to produce perfectly compliant code, as it cannot proceed if it introduces any remote resemblance of an issue.
• Agent Instructions: An agents.md file was created to provide the agent with a persistent set of rules and context. This file included:
  • A list of available commands (bun run typecheck, bun run test).
  • An explicit pointer to the cloned Effect repository: "You have access to the effect repository at repos/effect and you should use that to extract best practices."
  • Prohibitions on problematic behavior, such as running commands in watch mode, which would cause the agent to get stuck.

2. Pattern Extraction

Before writing any feature code, the agent was tasked with researching the cloned Effect repository to generate “pattern” files. This is a form of self-documentation where the agent codifies its learnings into markdown files for future reference.

• The agent was asked to explore the Effect repo and create patterns/http-api.md and patterns/sql.md.
• These files summarized the best practices for creating HTTP APIs, defining schemas, handling persistence with effect-sql, and generating OpenAPI documentation.
• This research phase ensures that the subsequent implementation aligns with the library’s idiomatic usage.

3. Implementation and Refinement

With the patterns established, the agent was instructed to build a “Todo” HTTP API.

• API and Persistence: The agent successfully implemented the API, including CRUD functionality, persistence using SQLite, and automatic OpenAPI spec generation. It correctly identified the relevant modules from the Effect codebase to accomplish this.
• Iterative Correction: The agent initially produced suboptimal code for tests, creating a custom wrapper function instead of using the standard it.layer utility from effect-test. This is a key part of the workflow:
  1. Identify a bad pattern: The speaker noticed the verbose and incorrect test setup.
  2. Provide direct feedback: The agent was explicitly told its code was poor and instructed to use the correct it.layer pattern.
  3. Codify the correction: After the agent fixed the tests, a new patterns/testing.md file was created to document the correct testing practice, preventing the agent from making the same mistake again. This continuous refinement of the pattern files is essential.

Advanced Concepts: Workflows and Clustering

For more complex, long-running, or failure-prone operations (e.g., a user registration process that involves a database write and an email dispatch), a simple request-response model is insufficient. If the server fails between the two steps, the system is left in an inconsistent state.

Effect provides effect-cluster and effect-workflow to solve this. Workflows guarantee that a multi-step process will eventually complete, even if the server crashes and the process has to be resumed on another node. This is particularly vital in AI-driven applications where operations (like LLM calls) can take minutes, significantly increasing the probability of failure during the process. The same “clone and extract patterns” approach can be used to teach the agent how to implement these robust, persistent workflows.

• Tags:
• Prompt Engineering
• LLM
• Coding Agents
• Software Architecture
• TypeScript
• Effect