Why AI Agents Need a Project Layer - Part 1

This article argues that modern AI coding assistants, while proficient at writing code, fail to understand the broader workflow and project context—such as tasks, rules, and decisions—that human developers manage. The author introduces the concept of a "project layer," an intermediate system that structures this living project state into data an AI agent can reliably access, rather than relying on manual translation or static files like Markdown. The piece sets up a series by focusing on this core problem, promising future discussions on architecture and specific tools.

This is the first part of a series about why even the most powerful AI agents today need more than just access to your codebase. They need access to the living state of the project: tasks, rules, decisions, notes, and workflow context. In this article, I focus on the core problem. I won’t dive into architecture, Freeform boards, Git integration, or Vibeocus Lens yet — those will come in later parts. Modern AI coding assistants have become very good at writing code. Give them a prompt like this: Fix coupon validation in the cart and add tests. …and you’ll often get working code, tests, and a decent explanation. This has become normal. However, in real development, a feature is almost never just one chat message. It comes with rich context: AI handles the code part well, but it often fails to understand the surrounding workflow. This is where the main problem begins. A typical flow looks like this: the developer copies information from a task into an AI chat, gets the result, then manually updates the task status, writes notes, creates follow-up tasks, and adds release comments. The AI session and the project management system live in parallel universes. The developer is forced to act as a constant translator between them. This is manageable when AI is used occasionally. When it becomes a daily tool, the constant manual bridging starts to hurt productivity. A Kanban board is great at visualizing workflow for humans. But an AI agent doesn’t live inside your head. It doesn’t automatically know why a task is important, which rules apply, which decisions are still valid, or what “done” actually means. Here’s what a task might look like as structured data: { "id": 108, "title": "Fix coupon validation in the cart", "status": "in-progress", "priority": "high", "description": "Coupons must not apply to discounted products. Update the server-side validation and add unit tests.", "start date": "2026-05-23", "due date": "2026-05-27" } This is already much better than a plain prompt. But for high-quality work, the agent often also needs project rules, active decisions, related documents, and notes. That’s why I’m not talking about just a better task tracker — I’m talking about a project layer. The board remains a useful interface for the human. The project layer makes the working context available to the AI agent in a structured way. Many developers have already tried to solve this problem with Markdown files, Obsidian, Logseq, or similar local knowledge bases. I did that too. This approach has real strengths: But over time, I ran into a limitation. A folder of Markdown files is good at storing text, but it is not very good at expressing workflow state. For example, it is hard for an agent to reliably understand: Markdown is still useful. But by itself, it is not a project layer for an AI agent. An AI can read a file. That is not the same as receiving a structured answer: here is the project, here are the active tasks, here are the rules, here are the related decisions, here are the allowed tools, and here is where notes live. I needed more than a set of files. I needed a layer that turns project context into data and actions an agent can understand. A project layer is an intermediate layer between an AI session and the real state of the project. It should not replace the code editor. It should not replace Git. It should not be another abstract board for the sake of having another board. Its job is simpler: give the AI agent access to the project context that the developer usually keeps in their head. For example: In other words, the project layer does not answer only "how should this code be written?" It also answers: "inside which project context should this code be written?" That distinction matters. MCP, the Model Context Protocol, becomes interesting exactly here. It gives AI clients a structured way to connect to external data and tools. Instead of manually pasting task descriptions, project rules, and notes into a chat every time, an AI agent can ask a local MCP server for that context. For example, before starting work, an agent could run something like this: vibeocus list projects vibeocus list tasks { "project id": 42, "status": "in-progress" } vibeocus get project rules { "project id": 42 } vibeocus list project decisions { "project id": 42, "status": "active" } In a simplified way, this turns project state into an API for the AI agent. Not a wall of text. Not a random folder of files. A set of clear requests and responses. For example, a project rule might look like this: - Validate input data with Zod. - Cart business logic lives in src/server/services/cart . - Route handlers must not contain business logic directly. - Do not add new dependencies without approval. - After TypeScript changes, run the linter and tests. If the agent sees this rule before changing the code, it is less likely to put business logic in the wrong place or add an unnecessary dependency. This does not make AI perfect. But it gives it a much better starting context. Vibeocus is my implementation of this kind of project layer. You can see it here → It keeps the project state local and exposes it to AI tools through a dedicated MCP helper vibeocus-mcp . Inside Vibeocus, there are tasks, rules, decisions, notes, documents, relations between projects, and other parts of project memory. For an AI agent, this is not just a UI. Through MCP, it can receive structured context and treat it as part of the development process. For the human, it remains a normal workspace: you can view tasks on a board, in a list, or in a calendar, read notes, and control changes. I do not want the agent to "take over" the project. A good workflow looks different: AI should not be a chaotic owner of the board. It should be a participant in the workflow: one that sees the right context and works inside clear boundaries. AI accelerates execution. But the faster execution becomes, the more visible coordination problems become. One AI session can include several things at once: From a coding perspective, that can be productive. From a project management perspective, it can quickly become noise if the result only stays inside a chat. That is why I believe the next important part of AI-assisted development is not only better code generation. The next important part is connecting AI sessions to project state. This first article is about the general pain, the idea of a project layer, and MCP as a way to connect an AI agent with project state. Next, I want to break Vibeocus down by layers so each part focuses on one concrete workflow instead of trying to describe the whole product at once: tasks , rules , and decisions give the agent working context before code changes.AI coding does not end with code generation. Real software work needs tasks, rules, decisions, memory, statuses, and coordination. If an AI agent helps write code, it should see at least part of that context in a structured way. That is what I call a project layer. Vibeocus is one implementation of that layer: a local workspace that connects project state with AI tools through MCP. I am curious how other developers are solving this problem. How do you connect AI coding sessions with the real tasks, rules, and decisions of your project? And does MCP feel like the right interface for this kind of project layer?