As developers, we’ve all been there – you’re working on a feature, an AI assistant helps you implement it, but then your teammate has no idea what happened or why certain decisions were made. The context is lost, the AI interaction history is gone, and your team is left to reverse-engineer the thought process.

This is the exact problem I set out to solve in my latest experiment with context-driven development, and the results led to a real fix in imdone 0.26.0 that improves how images render when syncing markdown content to Jira.

The Problem: Context Gets Lost

In my weekly experiments with imdone (a tool that keeps your backlog directly in your source code), I noticed a recurring issue: when one team member works with AI to solve a problem, the context and reasoning behind that collaboration doesn’t get passed to other humans on the team.

But there was also a technical problem to solve: images embedded in markdown list items weren’t rendering properly when synced to Jira. When you had content like this:

- Here's a bullet point with an image ![my-profile](./my-profile-image.jpeg)

Jira wouldn’t display the image correctly because it doesn’t handle images that appear directly in list items.

The Solution: Structured Context Format

I developed a structured markdown format for AI collaboration that ensures context is preserved and shareable across the team. Every task follows this format:

- [ ] <!-- Task title -->
- files:
- [<file description>](<file path>)
- [<file description>](<file path>)
- goal: <!-- what the change achieves -->
- constraints:
- <!-- constraint 1 -->
- <!-- constraint 2 -->
- action: apply patch and show diffs

Why This Works

1. Files: Explicitly lists which files are relevant, giving both AI and humans clear scope
2. Goal: States what the change should achieve in plain language
3. Constraints: Sets boundaries and requirements upfront
4. Action: Defines the expected deliverable

Real-World Application: Fixing Image Rendering

Using this format, I tackled the image rendering issue. Here’s how the task was structured:

- [ ] Fix image translation from markdown to JIRA and bullet items
- files:
- [markdown parser](cli-package/src/parsers/markdown-parser.js)
- [JIRA generator](cli-package/src/adapters/jira-generator.js)
- goal: If an image appears on a line of markdown that is an ordered or unordered list item, place it on a new line so JIRA renders it properly
- constraints:
- Write good tests to cover this case
- Don't break existing image rendering in other contexts
- action: apply patch and show diffs

The AI Collaboration Process

With this structured context, I simply told GitHub Copilot to “complete the task on line 28.” The AI:

1. Understood the scope by reading the specified files
2. Implemented test-driven development by writing failing tests first
3. Created the solution that moved images to new lines when they follow list items
4. Maintained backward compatibility as specified in constraints

The key insight: by providing structured context, the AI could work more effectively AND any teammate could understand exactly what was being attempted and why.

The Results: imdone 0.26.0

The fix successfully made it into imdone 0.26.0. Now when you have markdown content with images in list items, the sync process automatically moves images to separate lines, ensuring they render properly in Jira:

Before (broken in Jira):

- Here's a bullet point with an image ![profile](./image.jpeg)

After (renders correctly in Jira):

- Here's a bullet point with an image
![profile](./image.jpeg)

Key Takeaways

1. Structure Enables Better AI Collaboration

By providing files, goals, constraints, and expected actions upfront, AI assistants can work more effectively and deliver more predictable results.

2. Context Preservation is Critical for Teams

When AI interactions are structured and documented, teammates can understand not just what changed, but why and how decisions were made.

3. Experiments Drive Real Improvements

Treating every feature as an experiment means you’re always learning and improving. This “failed” interaction (there were some terminal issues during the process) still produced a working solution that benefits users.

4. Keep Context Close to Code

By storing these structured tasks in the same repository as the code (in our case, in a git-ignored backlog/ directory), context stays accessible without cluttering the main codebase.

The Philosophy: Features as Experiments

Every feature addition is really an experiment – you never know if it will truly benefit users until it’s in their hands. By treating development this way and tracking context systematically, we can:

• Make more informed decisions about what to build next
• Learn from both successes and failures
• Maintain better team alignment on goals and approaches
• Iterate more effectively based on user feedback

Try It Yourself

The structured context format I use is simple enough to adopt in any project:

1. Create tasks with explicit file lists, goals, and constraints
2. Store context where your team can access it (we use a git-ignored backlog directory)
3. Use the format consistently when working with AI assistants
4. Review and approve all AI-generated changes before merging

What’s Next?

This experiment convinced me that structured context makes AI collaboration more effective and team-friendly. I’ll continue refining this approach and testing it on more complex features.

The real win isn’t just the technical fix – it’s proving that we can work with AI in a way that enhances rather than replaces human collaboration and decision-making.

---

Want to see more experiments like this? I run these context-driven development experiments weekly. Follow along for more insights into AI-assisted development, team collaboration, and building better software tools.