The Markdown Operating System: Building an AI-Native Django Team

AI development becomes much more reliable when the team’s memory is written down. Instead of asking one general-purpose assistant to remember the product, architecture, and testing rules, I use a small team of specialized roles and a set of Markdown files that act as the project’s operating system.

The result is a practical workflow for building Django applications with ChatGPT and Codex: ideas enter as raw notes, specifications turn them into an agreed scope, and implementation is checked against the same written source of truth.

Why Markdown files?

Markdown is simple enough for people to read and structured enough for AI tools to use. Files can be reviewed in GitHub, changed through pull requests, linked from tickets, and passed between roles without being trapped in a chat transcript.

The files also make decisions durable. When a new engineer—or a new AI session—joins the work, it can read the project rules before making changes. That reduces repeated explanations and makes the quality bar visible.

The team I use

The team is made up of specialized roles. Some roles are performed by people, some by AI agents, and some are supervised combinations of both.

Business analyst

The business analyst starts with raw material: a rough idea, a customer request, or a short problem statement. The analyst asks what is missing, identifies assumptions, and turns the raw input into a clear initial specification.

This step is deliberately before product grooming. It gives the Product Manager something coherent to review instead of asking them to extract requirements from an unstructured note.

Product Manager

The Product Manager grooms the specification. They clarify scope, prioritize the outcome, identify acceptance criteria, and decide what belongs in the first version. The output is a requirement that the rest of the team can agree to build.

UI designer

The UI designer translates the approved requirements into page layouts, components, interaction behavior, responsive rules, accessibility notes, and UI acceptance criteria. This role is focused on the interface itself; it does not need to produce user journeys or UX research documents for every feature.

Technical Lead

The Technical Lead converts the groomed requirement into an implementation plan. They identify the relevant Django apps, APIs, services, models, permissions, and integration points. They also check that the proposed change fits the existing architecture.

Full-stack Django engineer

The Full-Stack Django Engineer implements the plan. Codex is useful here as an implementation partner: it can inspect the repository, make coordinated changes across models, views, templates, tests, and CSS, and explain the resulting diff.

The engineer remains responsible for the change. AI-generated code is a proposal until it passes the project’s tests and review rules.

Database architect

The Database Architect reviews schema changes, migrations, indexes, relationships, query patterns, and data integrity. This role is especially important when a small feature changes the long-term shape of the application’s data.

QA engineer

The QA Engineer turns acceptance criteria into tests and checks the finished behavior. QA verifies both the happy path and the boundaries described in the specification, including permissions, validation, responsive behavior, and regression risks.

Orchestrator

The Orchestrator coordinates the team. It selects the active module, provides each role with the relevant Markdown files, moves the work from one stage to the next, and checks that required artifacts exist before implementation proceeds.

The Orchestrator is not a replacement for the other roles. It is the workflow manager that keeps their outputs connected.

The team folder

The role definitions live together in a team/ folder so that every contributor and AI session can use the same responsibilities and handoff expectations:

team/
  business-analyst.md
  product-manager.md
  ui-designer.md
  technical-lead.md
  django-engineer.md
  database-architect.md
  qa-engineer.md

The Orchestrator is a role in the process rather than a separate orchestrator.md file. Its instructions are expressed through the project process, configuration, and active module files. This keeps coordination centralized without creating another role document that duplicates the workflow rules.

The Markdown project files

The project has a small set of global files that define how work should happen:

docs/
  github-workflow.md
  testing.md
  architecture.md
  process.md
  project-configuration.md
  modules/
    active-module.md

github-workflow.md defines branching, commits, pull requests, and deployment expectations. testing.md describes the test strategy and the minimum checks for a change. architecture.md records the application’s technical boundaries. process.md describes the handoffs between roles.

project-configuration.md tells the team which module is currently in scope and which rules apply. A module file then gives the feature-specific context: its goal, affected Django apps, database work, UI requirements, acceptance criteria, tests, dependencies, and constraints.

From raw idea to shipped feature

The workflow is intentionally staged:

1. A raw idea is captured without trying to solve it immediately.
2. The Business Analyst turns it into a structured specification.
3. The Product Manager grooms the scope and acceptance criteria.
4. The UI Designer defines the interface requirements.
5. The Technical Lead creates the implementation plan.
6. The Django Engineer implements the approved plan with Codex.
7. The Database Architect reviews data and migration changes.
8. The QA Engineer validates the feature against the specification.
9. The Orchestrator records the result and moves the module toward release.

Each handoff has a written artifact. If the next role cannot understand the work from the artifact, the workflow has found a gap early—before that gap becomes code.

What this changes

The biggest benefit is not simply speed. It is reduced ambiguity. The team has a shared place to answer questions such as: What are we building? Which module owns it? What does done mean? Which tests are required? What architectural constraints must be respected?

ChatGPT is useful for analysis, critique, planning, and review. Codex is useful for repository-aware implementation and test changes. Neither tool needs to pretend to be the entire team. The Markdown specifications provide the context, while the role structure provides accountability.

This approach also makes the process portable. A new project can reuse the global files, change the module configuration, and keep the same handoff pattern. Over time, the documents become a practical engineering playbook rather than a collection of one-off prompts.

Influence and further reading

This workflow is inspired by Alexey’s approach to AI-native development, especially the use of written specifications as the foundation for coordinating AI-assisted work. I adapted that specifications-first idea into a role-based Django team with Markdown files, a team/ folder, and an Orchestrator role.

Read: AI-Native Development: Specifications by Alexey.

The principle

The principle is simple: write down the work before asking AI to execute it, give each role a clear responsibility, and make every handoff inspectable.

An AI-native team is not just a developer with a chatbot. It is a coordinated system in which specifications, tools, tests, and human judgment reinforce one another.