I kept hitting the same wall with AI assistants. They’d misunderstand my context. They’d lose track of what I was building. Every new project meant starting from scratch.

I spent the first half of 2025 learning about AI. By June, I was ready to build.

The Problem

I was working with Cursor and Claude 3.5 Sonnet. The tools were capable. The problem was communication.

Every session, I found myself re-explaining context. Clarifying expectations that should have been obvious. The AI would suggest changes that didn’t align with what I was building. It wasn’t a capability problem. It was a shared understanding problem.

There had to be a better way.

The 9-Day Exploration

On June 28, 2025, I started a new repository: ai-instructions-wip-core.

The core idea was simple. Create a shared “Work In Progress” document that both the developer and the AI could reference. A living document that captured the current state, the goals, and the standards. Instead of re-explaining everything each session, point to the document.

What followed was nine days of rapid iteration.

Version 0.1.0 was a basic template. Just a structure for capturing project context.

Version 0.2.0 taught me that templates aren’t enough. I needed workflows. The AI needed to know not just what we were building, but how we were building it.

Version 0.5.0 was about standards. Not just what to do, but how to do it. Code style. Testing expectations. Documentation requirements. Before adding this, I was correcting the same issues over and over. After, the AI followed the standards consistently. The issue wasn’t that the AI couldn’t follow standards. I just hadn’t told it what they were.

Version 0.7.0 was where I learned about bloat. I had a habit of asking the AI “what questions do you have?” It would list dozens. I tried to answer all of them in the document. The result was unwieldy. Then I learned about context windows. At the time, the AI could retain full context for about 10 interactions back. A comprehensive document didn’t help if the AI couldn’t hold it all in context. So I trimmed. Removed edge cases that never came up. Focused on guardrails and constraints, not comprehensive answers. Less is more.

Version 1.0.0 arrived on July 6. Nine days after I started. A complete system for shared context between developer and AI.

What I Learned

Nine days of iteration taught me a pattern. The more structured the communication, the better AI performs. AI wants clarity on things we wouldn’t even think it would ask about.

Clear sections and consistent formatting reduce ambiguity. Shared context reduces misalignment. Focused constraints work better than exhaustive documentation.

Give the AI clear context, and it performs reliably. Give it vague context, and it improvises. Sometimes the improvisation works. Often it doesn’t.

What Happened Next

I never actually used the system on a real project.

I was working on a PHP extension of it when one of my team members started telling me about Claude Code. Planning mode. Agentic workflows. A tool built specifically for this kind of work. I put my project on hold. It made more sense to investigate Claude Code than to keep building my own system.

The tool became unnecessary. But the learning was still valuable. I didn’t know it at the time, but I was noticing something important. AI systems respond to clarity, precision, and structure. When the instructions I wrote were more precise, there was less ambiguity. They perform reliably when expectations are explicit. They struggle when things are vague. I got reinforcement on this observation during my Claude Code experimentation later that year.

By early July 2025, I was optimistic and pragmatic about AI. The tools worked well when I put in the effort to communicate clearly. Not fearful. Not worried. Just building better tools.

A few weeks later, I encountered a very different perspective on AI.

This is Part 1 of a 9-part series. Continue to Part 2: The Catalyst »