From vibe to structure: How Backlog.md transforms your development workflow

As developers, we often bounce between "just ship it" mode and "I should probably plan this," especially now when vibe coding is everywhere. Backlog.md bridges that gap elegantly. It's a markdown-native task manager that lives right in your git repo, bringing just enough structure without killing the flow.

The problem: UI polish in a time tracking app

I was working on TrackLab, my GitLab time tracking visualizer, when I noticed the legend. I just didn’t like how it was aligned. It took up too much space and felt off. A classic CSS annoyance, the kind where you just want to dive in and start tweaking. The legend items were using a grid layout that didn’t quite fit the look I wanted.

Enter Backlog.md

Instead of the usual "let me just fix this real quick" approach, I decided to try something different. With a simple backlog init, I transformed my project into a structured workspace.

Creating the task was straightforward. One command captured the requirement clearly: backlog task create with a clear description of what needs fixing.

The command where the first argument is the title of the task and the second flag defines the task description:

backlog task create "Compact legend of the time target" -d "The time target legend should be left-aligned. All three elements should be placed side by side. The existing labels and colors should be kept."

The Board View

What's powerful about Backlog.md is how it visualizes your work. The terminal based Kanban board gives you that satisfying overview without leaving your development environment.

AI Agent Integration

Here’s where it gets interesting: Backlog.md ships with Claude Code agent support. The agent markdown file is located here: .claude/agents/project-manager-backlog.md

After creating the task, I could simply tell Claude to implement it.

Claude Code reads the task details and creates a structured implementation plan. The agent followed the task specification exactly. No over engineering, no scope creep. Just clean execution of what was defined.

The agent can also create new tasks directly from your requirements, ensuring they follow proper format with title, description, and acceptance criteria. Most powerfully, it can break down complex features into atomic, independently completable tasks - just describe what you want to build and the agent will decompose it into a logical sequence of smaller tasks that can be tackled one at a time.

The result

The fix was simple but effective. Claude Code switched from grid to flexbox to make the layout cleaner and more balanced, reducing the unnecessary space the legend was taking up.

Legend items now wrap naturally and stay left aligned. And the Backlog.md board reflects the completed work.

The Claude Code agent that the Backlog.md tool created will also update tasks with the Implementation Plan and Implementation Notes details. It will also update the status, assignee, and final updated date of the task.

Why this matters

Backlog.md isn't about replacing your project management tool. It's about bringing lightweight structure to any development workflow. It captures tasks in markdown files that live with your code, tracks state changes through git, and provides just enough tooling to keep everyone organized. 

The real magic? It turns "vibe coding" into documented, traceable work without the overhead. Whether you're working solo, in a team, or with AI agents, having tasks defined in your repo means context never gets lost. 

Next time you're about to dive into a quick fix, consider spending 30 seconds to backlog task create it first. Your future self (and your teammates) will thank you. 

Check out https://github.com/MrLesk/Backlog.md for your next project. It's the structure you need without the friction you don't.