AI coding agents work best when everything they need lives in the repository, since the code is their source of truth. Yet most teams still track tasks and requirements in tools like Jira or Redmine that sit outside it. Storing tasks as simple Markdown files changes that: agents can read requirements and code in one place, and every task change is versioned and reviewable like any other commit.
The Docs as Code approach already offers a blueprint for this evolution. Documentation has already moved from separate software into Markdown files in a Git repository, often in a /docs folder inside the code repository. With AI coding agents, this becomes even more useful. Agents can read documentation to understand a system, make changes to the code, and update the relevant documentation within the same workflow.
The same principles apply to development tasks. When tasks are stored as Markdown files, agents can read them directly, use them to plan their work, and record results in the same files. This idea mirrors Spec-Driven Development, which uses Markdown specifications to define intended behavior before an AI agent implements it. A simple workflow has five steps: describe the task, have the agent analyze requirements, create an implementation plan, get developer approval, then implement and append a report to the task file.
The approval step keeps people in control, since the plan can be reviewed and corrected before any code changes. Because access needs differ, the author keeps code, documentation and tasks in three separate Git repositories. Tasks often contain sensitive information about unfinished security fixes or unannounced features, so a separate repository allows independent access control.
Source: Hacker News · Summarized by HeadlinesBriefing