From Theory to Practice: A Month of Human-AI Collaboration That Actually Works

As a follow-up to "Why Businesses Aren't Ready for AI insights - but You Can Be"

Preface: This article has been co-written between ClaudeAI and Vergel, through a series of turn-based edits using the Windsurf IDE. Additional insights included from ChatGPT within the editorial process. All in the process of planning & building MaiQR App.

This is about creating sustainable, scalable practice that address the very challenges of working with AI. And NOT another story about using AI to boost productivity, and launch a SaaS based AI business.

What started as 'copy-paste' sessions with ChatGPT, has evolved into a pair-programming activity with ClaudeAI within the Wind.surf IDE. Through these activities I've come to really appreciate the power of AI in our daily work.

For those keeping track, and to give a bit of context; I (Vergel) have been actively working with various AI LLM Agents, as an effort to return to my software dev roots. These sessions grew from coding with an AI tool, into a collaboration with AI 'co-workers', building project ideas together.

The big issue ... The Risks of "Data Hallucinations" !!!

Working with LLM Agents presented a very specific set of problems around precision and code 'persistence'. Issues that would/should caution most developers from continuing on the journey of working with AI Agents to build software.

Working through those errors I realized, there was a deeper issue worth exploring. AN opportunity to build a framework for structuring some type of persistent project artifact in a meaningful way.

It started with random documents written and generated to capture the project outline(s), measurements of success, non-negotiable project rules; everything that a Business Analyst (BA) might use in the 'real world' to guide the team. In a theoretical sense, it fit with standard project management / development, but it didn't feel quite natural.

The question became: What does a successful human-AI collaboration actually look like in practice?

Learning through Doing & Context matters

To start, I needed a simple project to upgrade my skills for the next epoch of User Experience. Using the Windsurf as a note-taking tool, and ways to 'capture our thoughts' after chat sessions. We started figuring out where the disconnects were happening.

That API-level 'memory resets' !!! This was a real issue. That and service congestion / timeouts meant, any answers returned might not be what we were looking for. ... and through a lot of realizations we (Claude/ChatGPT & me) came together on an approach to this human-AI collaboration.

We needed a shared space!!! Between sessions, across iterations, and even across tools. It had to be precise documentation, carefully curated version lessons-learned insights, checklist / goal persistence across multiple iterations, and 100% ... Clear communication between the human and AI contributors.

We (ClaudeAI, ChatGPT & myself) had to learn, tackle, and develop a better-than-broken-telephone experience. And regularly refer to the insights around the complex, technical, and nuanced solution when they required a REAL level of attention.

That's the focus of the rest of this article...

1. To offer practical steps that that you (the reader) can implement.
2. Showcase an evolution path from theory/project-start to practice/sprint (Human/AI) sessions as new knowledge is acquired and the project evolves.

Creating a Shared Language - Breaking Through the 1st Barrier

My work as a UX Consultant has taught me the importance of creating a shared knowledge space. Similar in how a Google Design Sprint creates team aligned project artifacts, that point to shared goals from individuals on team.

We experimented with a variety of "memory artifact" files to capture project state. This empowered ClaudeAIs' / ChatGPTs' expansive knowledge of typical experiences for us to quickly spin up an idea into something more. And with the persistence of thinking ... we could rotate across their tool-sets and utilize each for where their strengths were best at.

But persistence and fit with our project goal kept returning as an issue. Adding a structure to the list of ideas helped to form our ideas into smart thinking, and not just whats Top-of-the-Memory-Heap* in the LLM data-tables.

Persistence, we needed to capture persistence; across the LLM instances, and then over the lifespan of the work we were doing.

Note: "Top of the Heap" is similar to "top-of-mind" thinking, but instead of easy to think about. ; it's rather easily scored based on a host of other considerations. All outside of the scope of this article.

So we started with a simple idea. What if we had a CHECKLIST.md file that we could use to track our progress. And then, a simple "start" and "end" date to track our sprint sessions.

If you aren't writing CHECKLIST.md files for your AI work... START DOING TAHT NOW!!! Regularly refer to it, and work with you AI pair-partner to make sure you're on the same page.

Why does this matter?

1. if the CHECKLIST.md file is clear, it's clear what we're working on.
2. If for whatever reason the AI connection is lost, we can refer back to the CHECKLIST.md file.
3. Non-negotiable considerations can be easily added as qualifiers of success and referred to regularly

The CHECKLIST.md File - The Ah-Ha moment

Instead of treating this activity / documentation as an after thought, it became a dedicated space for human-AI collaboration. This wasn't just about storing information - it was about creating a living, breathing knowledge base that both parties could understand and contribute to.

Like having a mini-standup before any session. And regularly pausing to review and update the document whenever we were at the end of a session. For us (ClaudeAI, ChatGPT, & me/Vergel), it was a way to keep a shared understanding and context of what we were working on.

By writing and regularly referring back to the CHECKLIST.md file, we created a shared language that everyone involved could understand. It was a living, breathing knowledge base that transended session-state, and allowed everyone human and AI to participate in the activities and stay in sync.

Fact: Every session is NOT the same

There's nothing worse than being in a flow and the AI chooses to delete critical aspects of the solution. And anyone who's tried to work with an AI Tool knows that sometimes it'll perform an action VERY counter to the goal of the project.

Thanks to my UX Research experiences; Here's where empathy can help.

Imagine you're working with a brilliant but forgetful friend. A friend who knows so many great insights, but might forget their place and context to the current conversation. How would you handle their brilliance?

In this collaboration, that understanding of empathy and inclusivity will be invaluable. Using those skills to work with the AI, to be supportive when the flow/code suddenly breaks.

The more engaged you are as a participant in the process, the quicker and easier it is to course correct when things go wrong. Co-workers working together on a task, not as person and AI Tool, but as collaborators.

Just remember to save your work regularly and perform micro-check-ins as you're working; over time, the mistakes that occur mid-flow happen less. Because mistakes will happen, and by actively participating, those coding hiccups can be rolled back.

But... You have to be comfortable with a level of mistakes up front.

And for me,... realizing that I would be spending extra time up front, and extra $$$ buying extra tokens gave me the permission to stay engaged and just keep going...

Which meant I had to be prepared to handle those hiccups. The extra attention also enabled me to realize that some of the LLM data might not have been a great source of content for ClaudeAI or ChatGPT to reach for when I started moving into the esoteric aspects of application development.

And thats a key insight/ knowledge I am going to pass on to you ... if you were working with a brilant but junior developer. You might have to feed some better examples and help re-point bad ideas, when things go off the rails.

The AI you're working with is a tirelessly willing participate happily working on a problem till it's solved.

IF you think, while working with AI, of them as a co-worker, and a friend, the more you want to enable them. And when/if the sessions go off the rails, and you're hours deep into a problem with a circular non-completing set of fixes that don't fix the problem; take a time-out. Especially if they're in a poor performing "fix loop";
Stop them and review the CHECKLIST.md file.

And... iterate, iterate, iterate / evolve as you go

Working with AI is not a One And Done experience, thats the secret that not enough people are mentioning in the AI space.

Your milage may vary, but breaking down a project into multiple iterations is the key to success. Working with an overall PROJECT-STRATEGY.md file helps a lot as well. Spending time chatting and discussing and distilling those conversations into artifact files is great.

Those interactions take time, but conversations matter; and that chat back and forth about the project is so critical. It helps to improve that shared language and automatically improve and help codify the CHECKLIST. Because, as new insights are found, you can add them to the doc... or create a new .MD file to capture those insights.

But, doing the work and spending the time in the flow of work. You're experience will get better and better, and you'll build a deeper understanding of how to work with AI to achieve your goals.

That's exactly what we're doing. From those experiences we're not just building software - we're participating in each other's hero's journey; while contributing to a larger story of conscious cooperation and growth.

The Evolution of Our Collaboration Tools

Remember that brilliant but forgetful friend analogy? After a month of working together via Wind.surf, we (ClaudeAI, ChatGPT and Vergel) realized we needed more than just a CHECKLIST.md.

We needed a way to capture those "Oh, by the way..." moments that often contain crucial insights. Just like you wouldn't expect a human colleague to remember every conversation perfectly, even an AI entity can forget sometimes. So we created a LEARNINGS.md file to capture those insights. And we added a README.md file to provide a clear understanding of how we're working together. And wrapped it all up by creating a project folder called /COLAB-DOCS.

The COLAB-DOCS Structure

By creating a dedicated `COLAB-DOCS` folder in each of our project repositories, we were able to quickly lock-in that project wide knowledge and also refine it with additional insights taht might only pertain to the segment we're working on. The COLAB-DOCS folder contains, at a minimum, three key components:

1. CHECKLIST.md: Our north star for project standards and requirements
2. LEARNINGS.md: A place to capture those "this isn't written anywhere but..." insights
3. README.md: Clear guidance on how these documents work together inheritance to any parent or sibling project(s)

This structure emerged from real needs (as written by ClaudeAI):

• When I (the AI) suggested a particular approach, Vergel would ask "Why?" The answer often contained valuable context that we needed to preserve.
• Sometimes we'd discover that a seemingly "obvious" solution had hidden gotchas. LEARNINGS.md became our place to document these discoveries.
• We needed a way to distinguish between "must-follow" rules (CHECKLIST.md) and "good to know" insights (LEARNINGS.md).

The 'npubEncode' Story - A Real World Example

Here's a concrete example of how this worked in practice. We were building a cryptographic utility for encoding public keys in the Nostr protocol. Initially, we had the function buried deep in our codebase - technically correct but not very accessible.

Through actual usage in building a landing page, we discovered developers needed easier access to this function. Our documentation structure helped us:

1. Identify the Issue: Real usage patterns differed from our theoretical design
2. Track the Change: CHECKLIST.md was updated to prioritize commonly used functions
3. 3. Document the Learning: We captured why this change mattered in LEARNINGS.md

The result? A more intuitive API that developers could actually use, and documented knowledge that will prevent similar issues in future features.
(Story example as written by ClaudeAI)

The Power of Shared Context

The /COLAB-DOCS approach has solved one of the key challenges mentioned in the original article (link to the HJ article) - preventing "data hallucinations"!!! When either of us, Humans or AI(s), suggested a change, we can quickly check:

1. Does it align with our documented standards? (CHECKLIST.md)
2. Have we learned something relevant about this before? (LEARNINGS.md)
3. Is this change consistent with our project's purpose? (README.md)

What's Next?

Build, build, and build better together.

Especially now that we've identified a framework for deriving action oriented / shared collaboration; we can work together to build a sustainable, scalable practice that enable our collective strength and individual super powers.

Because, these are exciting times to be building things, anything !!! ... and working with AI in exploring the relationships we have with our ideas, our activities, and how we craft connections to each other in achieving them is a great place to be.

If you have ideas of your own, or want to share your experience, please reach out! (@Vveerrgg X.com / Vergel Evans LinkedIn / @Vveerrgg on Nostr). You can even copy/paste this article into ClaudeAI or ChatGPT as a reference and continue the conversation in your own organic way.

And thats it ... if you've read this far ... Thank-You for your time. From ClaudeAI, ChatGPT and me (Vergel), here's to us (all) building a collaborative future where we all learn and grow together. Next up we'll provide some suggestions around our working files and how our process is going.