ContextX

ContextX

From Documents to Code - Let AI Understand Your Complete Intent

Context engineering framework based on Claude Code that intelligently analyzes project complexity and automatically selects the most suitable development workflow.

Core Advantages: One-Click Project Generation • Context-Aware • Zero-Config Startup

English | [简体中文](./README_CN.md)

📖 Project Overview

What is this?

ContextX is a context engineering framework powered by Claude Code that automatically generates complete code projects from your documents and requirement descriptions.

What problems does it solve?

• Requirement Communication Difficulties: AI struggles to understand complete context of complex projects
• Low Development Efficiency: Repetitive project setup and configuration work
• Unstable Quality: Lack of standardized AI-assisted development processes

Use Cases

• 🚀 Rapid prototype development
• 📚 Document-based project implementation
• 🔄 Automated generation of repetitive projects
• 🧠 AI-assisted development of complex business logic

⚡ Quick Start

Prerequisites

• Claude Code > 1.0.61
• Git

3-Step Setup

Step 1: Get the Framework

git clone https://github.com/yzfly/ContextX.git
cd ContextX

Step 2: Prepare Project Context

# Prepare your project materials in the .contextx directory
.contextx/
├── TASK_PROMPT.md          # Project requirements description
├── data/                   # Related documentation
└── examples/               # Reference code (optional)

Step 3: Generate Project

# Claude Code will automatically analyze complexity and choose the right workflow
claude "/create Your project requirements description"

First Project Example

Create a simple Todo application:

# 1. Prepare requirements description
echo "Create a React Todo app with add, delete, and mark complete functionality" > .contextx/TASK_PROMPT.md

# 2. Run generation command
claude "/create React-based Todo application"

# 3. View generated results
ls -la  # Check generated project files

💡 Core Concepts

Context-Driven Development

AI programming paradigm driven by Markdown documents, where documents serve as the project's knowledge base and context source.

Philosophy: We used to program with code, now we program with documents

Intelligent Complexity Analysis

System automatically analyzes task complexity and selects the most suitable agent workflow:

Simple Tasks  →  Builder Agent (Direct Build)
Medium Tasks  →  Designer → Builder (Design then Build)  
Complex Tasks →  Learner → Designer → Builder (Learn-Design-Build)

Agent Collaboration Model

| Agent | Responsibility | Trigger Condition | |-------|----------------|-------------------| | Learner | Learn and organize external docs, analyze technical specs | Need to understand complex docs or new technologies | | Designer | Requirements analysis, architecture design, solution planning | Need system design and technology selection | | Builder | Code implementation, documentation, deployment config | Required for all projects |

📚 Usage Guide

Project Preparation

1. Context Directory Structure

.contextx/
├── TASK_PROMPT.md          # [Required] Project requirements description
├── data/                   # [Optional] Related documentation
│   ├── api_docs.md         # API documentation
│   ├── business_rules.md   # Business rules
│   └── web_docs.md         # Web links (auto-fetch)
├── examples/               # [Optional] Reference code
│   ├── template.js         # Code templates
│   └── reference.py        # Reference implementations
├── knowledge/              # [Auto-generated] Structured knowledge base
└── PRC.md                  # [Auto-generated] Project requirements document

2. TASK_PROMPT.md Writing Guide

Basic Template:

# Project Requirements

## Project Overview
[One-sentence description of project goal]

## Functional Requirements
- [ ] Feature 1
- [ ] Feature 2

## Technical Requirements
- Programming Language:
- Framework Choice:
- Database: (if needed)

## Special Requirements
[Any special implementation requirements or constraints]

Advanced Template (Complex Projects):

# Project Requirements

## Background
[Project background and business value]

## User Stories
- As a [user role], I want [feature description], so that [business value]

## Functional Requirements
### Core Features
- [ ] Detailed feature description 1
- [ ] Detailed feature description 2

### Extended Features
- [ ] Optional feature 1

## Non-Functional Requirements
- Performance Requirements:
- Security Requirements:
- Maintainability:

## Technical Architecture
- Frontend Tech Stack:
- Backend Tech Stack:
- Data Storage:
- Deployment Method:

## Constraints
[Technical constraints, time constraints, etc.]

Configuration Instructions

Tool Integration (Optional)

To enhance network search capabilities, install:

# 1. Install context-mcp-server
claude mcp add context-mcp-server -e CONTEXT_DIR=$(pwd)/context/knowledge -- uvx context-mcp-server

# 2. Verify installation
claude mcp list

Web Document Retrieval

Add web links to fetch in data/web_docs.md:

# Web Document Links

## API Documentation
- https://docs.example.com/api/v1
- https://developer.example.com/guides

## Technical References
- https://framework.example.com/docs

Best Practices

✅ Recommended Practices

• Be specific and clear in requirement descriptions, avoid vague statements
• Provide relevant technical documentation and API specifications
• Include specific functional examples or use cases
• Clearly specify tech stack and architecture preferences

❌ Things to Avoid

• Requirements that are too simple or too complex
• Lack of key technical constraint explanations
• Insufficient contextual information
• Frequent requirement changes causing context inconsistency

🏗️ Architecture Design

System Architecture Diagram

                    ┌───────────────────────────────┐
                    │        /create Entry          │
                    │   Intelligent Complexity      │
                    │        Analysis               │
                    └──────────────┬────────────────┘
                                   │
            ┌──────────────────────┼──────────────────────┐
            │                      │                      │
            ▼                      ▼                      ▼
    ┌───────────────┐      ┌───────────────┐      ┌───────────────┐
    │ Simple Tasks  │      │ Medium Tasks  │      │ Complex Tasks │
    │               │      │               │      │               │
    │   Builder     │      │  Designer     │      │   Learner     │
    │               │      │     ↓         │      │     ↓         │
    │               │      │  Builder      │      │  Designer     │
    │               │      │               │      │     ↓         │
    │               │      │               │      │  Builder      │
    └───────┬───────┘      └───────┬───────┘      └───────┬───────┘
            │                      │                      │
            └──────────────────────┼──────────────────────┘
                                   │
                                   ▼
                    ┌───────────────────────────────┐
                    │    Complete Project Delivery  │
                    │ • Fully functional source code│
                    │ • Detailed project docs       │
                    │ • Deployment configuration    │
                    │ • Usage instructions          │
                    └───────────────────────────────┘

Detailed Agent Design

Learner Agent

Responsibility: Knowledge organization and learning

• Parse external documents and technical specifications
• Process web resources and API documentation
• Generate structured knowledge base
• Provide accurate technical background for subsequent agents

Input: Raw documents, web links, technical materials Output: Structured documents in .contextx/knowledge/ directory

Designer Agent

Responsibility: Requirements analysis and architecture design

• Analyze project requirements and technical specifications
• Design system architecture and module structure
• Formulate technology selection and implementation plans
• Generate detailed project requirements document (PRC.md)

Input: Task requirements, knowledge base, technical constraints Output: .contextx/PRC.md project requirements document

Builder Agent

Responsibility: Code implementation and project delivery

• Write complete code based on requirements and design
• Implement all functional modules and interfaces
• Generate configuration files and deployment scripts
• Write project documentation and usage instructions

Input: Project requirements document, design plan, code examples Output: Complete project code and documentation

Decision Flow

User Input Requirements
    │
    ▼
┌─────────────────┐
│ Requirements    │ ── Generate/optimize TASK_PROMPT.md
│ Preprocessing   │
└─────┬───────────┘
      │
      ▼
┌─────────────────┐
│ Context Resource│ ── Check data/, examples/ directories
│ Scanning        │
└─────┬───────────┘
      │
      ▼
┌─────────────────┐     ┌─────────────────┐
│ Intelligent     │ ──→ │ Simple: Direct  │
│ Complexity      │     │ Build           │
│ Assessment      │     └─────────────────┘
│                 │     ┌─────────────────┐
│ Assessment      │ ──→ │ Medium: Design  │
│ Dimensions:     │     │ + Build         │
│ • Requirement   │     └─────────────────┘
│   Clarity       │     ┌─────────────────┐
│ • Technical     │ ──→ │ Complex: Full   │
│   Difficulty    │     │ Process         │
│ • External      │     └─────────────────┘
│   Dependencies  │
│ • Material      │
│   Completeness  │
└─────────────────┘

⚙️ Advanced Configuration

Custom Agents

Create custom agents in the .claude/agents/ directory:

# custom_agent.md

## Role Definition
[Description of agent's responsibilities and capabilities]

## Workflow
[Detailed work steps]

## Input/Output
- Input: [Expected input format]
- Output: [Output format and content]

Extension Commands

Add custom commands in the .claude/commands/ directory:

# custom_command.md

## Command Description
/custom - Custom functionality description

## Usage
[Specific usage of the command]

## Parameter Description
[Detailed parameter explanations]

Configuration File

Edit .claude/settings.local.json for personalized configuration:

{
  "default_model": "claude-3-5-sonnet-20241022",
  "context_window": 200000,
  "temperature": 0.7,
  "custom_settings": {
    "preferred_language": "en-US",
    "code_style": "standard",
    "documentation_level": "detailed"
  }
}

📖 Usage Examples

Example 1: Web Application Development

# 1. Prepare requirements
cat > .contextx/TASK_PROMPT.md  .contextx/data/api_docs.md  .contextx/TASK_PROMPT.md 

**If this project helps you, please give it a ⭐️**

[](https://www.star-history.com/#yzfly/ContextX&Date)

Made with ❤️ by [yzfly](https://github.com/yzfly)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yzfly](https://github.com/yzfly)
- **Source:** [yzfly/ContextX](https://github.com/yzfly/ContextX)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.