Context-Driven Development

Treat project context as a first-class artifact managed alongside code. Instead of relying on ad-hoc prompts or scattered documentation, establish a persistent, structured foundation that informs all AI interactions.

Installation

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install context-driven-development

WHAT This Skill Does

Creates and maintains a set of context documents that:

• Define what you're building and why (product.md)
• Specify technology choices and constraints (tech-stack.md)
• Establish how the team works (workflow.md)
• Track what's happening (tracks.md)

WHEN to Use

Use for:

• Setting up new projects with AI-assisted development
• Onboarding team members to existing codebases
• Ensuring consistent AI behavior across sessions
• Documenting decisions that affect code generation
• Managing projects with multiple contributors or AI assistants

Skip for:

• Solo experiments or throwaway prototypes
• Single-file scripts
• Projects without AI assistance

Keywords: context, project setup, documentation, AI alignment, team workflow, product vision, tech stack

Core Philosophy

Context precedes code.
Living documentation.
Single source of truth.
AI alignment.

1. Context precedes code — Define what you're building and how before implementation
2. Living documentation — Context artifacts evolve with the project
3. Single source of truth — One canonical location for each type of information
4. AI alignment — Consistent context produces consistent AI behavior

The Workflow

Context → Spec & Plan → Implement

1. Context Phase: Establish or verify project context artifacts exist and are current
2. Specification Phase: Define requirements and acceptance criteria for work units
3. Planning Phase: Break specifications into phased, actionable tasks
4. Implementation Phase: Execute tasks following established workflow patterns

The Context Documents

product.md — WHAT and WHY

Purpose: Captures product vision, goals, target users, and business context.

Contents:

• Product name and one-line description
• Problem statement and solution approach
• Target user personas
• Core features and capabilities
• Success metrics and KPIs
• Product roadmap (high-level)

Update when:

• Product vision or goals change
• New major features are planned
• Target audience shifts

tech-stack.md — WITH WHAT

Purpose: Documents technology choices, dependencies, and architectural decisions.

Contents:

• Primary languages and frameworks
• Key dependencies with versions
• Infrastructure and deployment targets
• Development tools and environment
• Testing frameworks
• Code quality tools

Update when:

• Adding new dependencies
• Upgrading major versions
• Changing infrastructure
• Adopting new tools or patterns

workflow.md — HOW to Work

Purpose: Establishes development practices, quality gates, and team workflows.

Contents:

• Development methodology (TDD, trunk-based, etc.)
• Git workflow and commit conventions
• Code review requirements
• Testing requirements and coverage targets
• Quality assurance gates
• Deployment procedures

Update when:

• Team practices evolve
• Quality standards change
• New workflow patterns are adopted

tracks.md — WHAT'S HAPPENING

Purpose: Registry of all work units with status and metadata.

Contents:

• Active tracks with current status
• Completed tracks with completion dates
• Track metadata (type, priority, assignee)
• Links to individual track specs

Update when:

• New work starts
• Work status changes
• Work completes

Directory Structure

context/
├── product.md            # Product vision and goals
├── tech-stack.md         # Technology choices
├── workflow.md           # Development practices
├── tracks.md             # Work unit registry
└── styleguides/          # Language-specific conventions
    ├── python.md
    ├── typescript.md
    └── ...

Setup: New Project (Greenfield)

For new projects, create all artifacts from scratch:

1. Create context/product.md:

• Define the problem you're solving
• Describe target users
• List core features for v1
• Define success metrics

1. Create context/tech-stack.md:

• Choose languages and frameworks
• Document key dependencies with versions
• Specify infrastructure targets
• List development tools

1. Create context/workflow.md:

• Define branching strategy
• Set commit conventions
• Establish testing requirements
• Document deployment process

1. Create context/tracks.md:

• Start with empty registry
• Add work units as they're created

Setup: Existing Project (Brownfield)

For existing codebases, extract context from what exists:

1. Analyze the codebase:

• Read package.json, requirements.txt, go.mod, etc.
• Look at existing README and docs
• Check git history for patterns

1. Create context/tech-stack.md:

• Document discovered dependencies
• Note infrastructure from configs (Docker, CI, etc.)

1. Create context/product.md:

• Infer product purpose from code
• Document current feature set
• Note any README content

1. Create context/workflow.md:

• Document existing practices
• Note any established patterns

Maintenance Principles

Keep Artifacts Synchronized

Changes in one artifact should reflect in related documents:

• New feature in product.md → Update tech-stack.md if new dependencies needed
• Completed track → Update product.md to reflect new capabilities
• Workflow change → Update all affected track plans

Update tech-stack.md When Adding Dependencies

Before adding any new dependency:

1. Check if existing dependencies solve the need
2. Document the rationale for new dependencies
3. Add version constraints
4. Note any configuration requirements

Verify Context Before Implementation

Before starting any work:

1. Read all context artifacts
2. Flag any outdated information
3. Propose updates before proceeding
4. Confirm context accuracy

Validation Checklist

Before starting implementation, validate:

Product Context:

• [ ] product.md reflects current vision
• [ ] Target users are accurately described
• [ ] Feature list is up to date

Technical Context:

• [ ] tech-stack.md lists all current dependencies
• [ ] Version numbers are accurate
• [ ] Infrastructure targets are correct

Workflow Context:

• [ ] workflow.md describes current practices
• [ ] Quality gates are defined
• [ ] Commit conventions are documented

Anti-Patterns

| Anti-Pattern | Problem | Fix |

|--------------|---------|-----|

| Stale Context | Documents become outdated and misleading | Update context as part of each track's completion |

| Context Sprawl | Information scattered across multiple locations | Use defined artifact structure; resist new document types |

| Implicit Context | Relying on knowledge not captured in artifacts | If referenced repeatedly, add to appropriate artifact |

| Over-Specification | Context so detailed it's impossible to maintain | Keep focused on decisions affecting AI behavior and team alignment |

Session Continuity

Starting a New Session

1. Read context/product.md to orient yourself
2. Check context/tracks.md for active work
3. Read relevant track specs for current task
4. Verify context artifacts are current

Ending a Session

1. Update track status with current progress
2. Note any blockers or decisions made
3. Commit in-progress work with clear status
4. Update tracks.md if status changed

Benefits

Team Alignment:

• New team members onboard faster with explicit context
• Consistent terminology across the team
• Shared understanding of product goals

AI Consistency:

• AI assistants produce aligned outputs across sessions
• Reduced need to re-explain context
• Predictable behavior based on documented standards

Institutional Memory:

• Decisions and rationale are preserved
• Context survives team changes
• Historical context informs future decisions

NEVER Do

1. NEVER start implementation without reading context — context precedes code
2. NEVER add dependencies without updating tech-stack.md — keep the source of truth current
3. NEVER let context documents get stale — update them as part of completing work
4. NEVER scatter context across ad-hoc documents — use the defined structure
5. NEVER assume AI remembers previous sessions — context must be in artifacts
6. NEVER skip context for "quick" changes — small changes compound into drift