{"id":30620488,"url":"https://github.com/yzfly/contextx","last_synced_at":"2025-08-30T13:37:56.282Z","repository":{"id":306738135,"uuid":"1027068861","full_name":"yzfly/ContextX","owner":"yzfly","description":"ContextX: Context-driven AI development framework powered by Claude Code. Transform documents into complete projects with intelligent agent workflows.","archived":false,"fork":false,"pushed_at":"2025-08-04T23:34:45.000Z","size":88,"stargazers_count":21,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-05T01:16:00.077Z","etag":null,"topics":["claude","claude-ai","claude-code","claude-dekstop","claude4","context-engineer","context-engineering","mcp"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yzfly.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-27T08:41:30.000Z","updated_at":"2025-08-04T23:34:48.000Z","dependencies_parsed_at":"2025-07-27T10:32:19.170Z","dependency_job_id":"90566459-7d84-4f82-a10f-386ba7cfc3a3","html_url":"https://github.com/yzfly/ContextX","commit_stats":null,"previous_names":["yzfly/contextclaude","yzfly/contextx"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/yzfly/ContextX","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yzfly%2FContextX","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yzfly%2FContextX/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yzfly%2FContextX/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yzfly%2FContextX/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yzfly","download_url":"https://codeload.github.com/yzfly/ContextX/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yzfly%2FContextX/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272858485,"owners_count":25005092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-ai","claude-code","claude-dekstop","claude4","context-engineer","context-engineering","mcp"],"created_at":"2025-08-30T13:37:55.596Z","updated_at":"2025-08-30T13:37:56.267Z","avatar_url":"https://github.com/yzfly.png","language":"Shell","readme":"# ContextX\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://files.mdnice.com/user/43439/1668dfff-b9b9-4b58-a228-0009bcb8e47d.jpg\" alt=\"ContextX Logo\" width=\"400\"/\u003e\n  \u003cbr/\u003e\u003cbr/\u003e\n  \n![GitHub stars](https://img.shields.io/github/stars/yzfly/ContextX?style=social)\n![GitHub forks](https://img.shields.io/github/forks/yzfly/ContextX?style=social)\n![GitHub issues](https://img.shields.io/github/issues/yzfly/ContextX)\n![GitHub license](https://img.shields.io/github/license/yzfly/ContextX)\n![Version](https://img.shields.io/badge/version-1.0-blue)\n\n**From Documents to Code - Let AI Understand Your Complete Intent**\n\nContext engineering framework based on Claude Code that intelligently analyzes project complexity and automatically selects the most suitable development workflow.\n\n**Core Advantages:** One-Click Project Generation • Context-Aware • Zero-Config Startup\n\nEnglish | [简体中文](./README_CN.md)\n\n\u003c/div\u003e\n\n## 📖 Project Overview\n\n### What is this?\nContextX is a context engineering framework powered by Claude Code that automatically generates complete code projects from your documents and requirement descriptions.\n\n### What problems does it solve?\n- **Requirement Communication Difficulties**: AI struggles to understand complete context of complex projects\n- **Low Development Efficiency**: Repetitive project setup and configuration work\n- **Unstable Quality**: Lack of standardized AI-assisted development processes\n\n### Use Cases\n- 🚀 Rapid prototype development\n- 📚 Document-based project implementation\n- 🔄 Automated generation of repetitive projects\n- 🧠 AI-assisted development of complex business logic\n\n## ⚡ Quick Start\n\n### Prerequisites\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) \u003e 1.0.61\n- Git\n\n### 3-Step Setup\n\n**Step 1: Get the Framework**\n```bash\ngit clone https://github.com/yzfly/ContextX.git\ncd ContextX\n```\n\n**Step 2: Prepare Project Context**\n```bash\n# Prepare your project materials in the .contextx directory\n.contextx/\n├── TASK_PROMPT.md          # Project requirements description\n├── data/                   # Related documentation\n└── examples/               # Reference code (optional)\n```\n\n**Step 3: Generate Project**\n```bash\n# Claude Code will automatically analyze complexity and choose the right workflow\nclaude \"/create Your project requirements description\"\n```\n\n### First Project Example\n\nCreate a simple Todo application:\n\n```bash\n# 1. Prepare requirements description\necho \"Create a React Todo app with add, delete, and mark complete functionality\" \u003e .contextx/TASK_PROMPT.md\n\n# 2. Run generation command\nclaude \"/create React-based Todo application\"\n\n# 3. View generated results\nls -la  # Check generated project files\n```\n\n## 💡 Core Concepts\n\n### Context-Driven Development\nAI programming paradigm driven by Markdown documents, where documents serve as the project's knowledge base and context source.\n\n**Philosophy:** *We used to program with code, now we program with documents*\n\n### Intelligent Complexity Analysis\nSystem automatically analyzes task complexity and selects the most suitable agent workflow:\n\n```\nSimple Tasks  →  Builder Agent (Direct Build)\nMedium Tasks  →  Designer → Builder (Design then Build)  \nComplex Tasks →  Learner → Designer → Builder (Learn-Design-Build)\n```\n\n### Agent Collaboration Model\n\n| Agent | Responsibility | Trigger Condition |\n|-------|----------------|-------------------|\n| **Learner** | Learn and organize external docs, analyze technical specs | Need to understand complex docs or new technologies |\n| **Designer** | Requirements analysis, architecture design, solution planning | Need system design and technology selection |\n| **Builder** | Code implementation, documentation, deployment config | Required for all projects |\n\n## 📚 Usage Guide\n\n### Project Preparation\n\n#### 1. Context Directory Structure\n```\n.contextx/\n├── TASK_PROMPT.md          # [Required] Project requirements description\n├── data/                   # [Optional] Related documentation\n│   ├── api_docs.md         # API documentation\n│   ├── business_rules.md   # Business rules\n│   └── web_docs.md         # Web links (auto-fetch)\n├── examples/               # [Optional] Reference code\n│   ├── template.js         # Code templates\n│   └── reference.py        # Reference implementations\n├── knowledge/              # [Auto-generated] Structured knowledge base\n└── PRC.md                  # [Auto-generated] Project requirements document\n```\n\n#### 2. TASK_PROMPT.md Writing Guide\n\n**Basic Template:**\n```markdown\n# Project Requirements\n\n## Project Overview\n[One-sentence description of project goal]\n\n## Functional Requirements\n- [ ] Feature 1\n- [ ] Feature 2\n\n## Technical Requirements\n- Programming Language:\n- Framework Choice:\n- Database: (if needed)\n\n## Special Requirements\n[Any special implementation requirements or constraints]\n```\n\n**Advanced Template (Complex Projects):**\n```markdown\n# Project Requirements\n\n## Background\n[Project background and business value]\n\n## User Stories\n- As a [user role], I want [feature description], so that [business value]\n\n## Functional Requirements\n### Core Features\n- [ ] Detailed feature description 1\n- [ ] Detailed feature description 2\n\n### Extended Features\n- [ ] Optional feature 1\n\n## Non-Functional Requirements\n- Performance Requirements:\n- Security Requirements:\n- Maintainability:\n\n## Technical Architecture\n- Frontend Tech Stack:\n- Backend Tech Stack:\n- Data Storage:\n- Deployment Method:\n\n## Constraints\n[Technical constraints, time constraints, etc.]\n```\n\n### Configuration Instructions\n\n#### Tool Integration (Optional)\nTo enhance network search capabilities, install:\n\n```bash\n# 1. Install context-mcp-server\nclaude mcp add context-mcp-server -e CONTEXT_DIR=$(pwd)/context/knowledge -- uvx context-mcp-server\n\n# 2. Verify installation\nclaude mcp list\n```\n\n#### Web Document Retrieval\nAdd web links to fetch in `data/web_docs.md`:\n\n```markdown\n# Web Document Links\n\n## API Documentation\n- https://docs.example.com/api/v1\n- https://developer.example.com/guides\n\n## Technical References\n- https://framework.example.com/docs\n```\n\n### Best Practices\n\n#### ✅ Recommended Practices\n- Be specific and clear in requirement descriptions, avoid vague statements\n- Provide relevant technical documentation and API specifications\n- Include specific functional examples or use cases\n- Clearly specify tech stack and architecture preferences\n\n#### ❌ Things to Avoid\n- Requirements that are too simple or too complex\n- Lack of key technical constraint explanations\n- Insufficient contextual information\n- Frequent requirement changes causing context inconsistency\n\n## 🏗️ Architecture Design\n\n### System Architecture Diagram\n\n```\n                    ┌───────────────────────────────┐\n                    │        /create Entry          │\n                    │   Intelligent Complexity      │\n                    │        Analysis               │\n                    └──────────────┬────────────────┘\n                                   │\n            ┌──────────────────────┼──────────────────────┐\n            │                      │                      │\n            ▼                      ▼                      ▼\n    ┌───────────────┐      ┌───────────────┐      ┌───────────────┐\n    │ Simple Tasks  │      │ Medium Tasks  │      │ Complex Tasks │\n    │               │      │               │      │               │\n    │   Builder     │      │  Designer     │      │   Learner     │\n    │               │      │     ↓         │      │     ↓         │\n    │               │      │  Builder      │      │  Designer     │\n    │               │      │               │      │     ↓         │\n    │               │      │               │      │  Builder      │\n    └───────┬───────┘      └───────┬───────┘      └───────┬───────┘\n            │                      │                      │\n            └──────────────────────┼──────────────────────┘\n                                   │\n                                   ▼\n                    ┌───────────────────────────────┐\n                    │    Complete Project Delivery  │\n                    │ • Fully functional source code│\n                    │ • Detailed project docs       │\n                    │ • Deployment configuration    │\n                    │ • Usage instructions          │\n                    └───────────────────────────────┘\n```\n\n### Detailed Agent Design\n\n#### Learner Agent\n**Responsibility:** Knowledge organization and learning\n- Parse external documents and technical specifications\n- Process web resources and API documentation\n- Generate structured knowledge base\n- Provide accurate technical background for subsequent agents\n\n**Input:** Raw documents, web links, technical materials\n**Output:** Structured documents in `.contextx/knowledge/` directory\n\n#### Designer Agent  \n**Responsibility:** Requirements analysis and architecture design\n- Analyze project requirements and technical specifications\n- Design system architecture and module structure\n- Formulate technology selection and implementation plans\n- Generate detailed project requirements document (PRC.md)\n\n**Input:** Task requirements, knowledge base, technical constraints\n**Output:** `.contextx/PRC.md` project requirements document\n\n#### Builder Agent\n**Responsibility:** Code implementation and project delivery\n- Write complete code based on requirements and design\n- Implement all functional modules and interfaces\n- Generate configuration files and deployment scripts\n- Write project documentation and usage instructions\n\n**Input:** Project requirements document, design plan, code examples\n**Output:** Complete project code and documentation\n\n### Decision Flow\n\n```\nUser Input Requirements\n    │\n    ▼\n┌─────────────────┐\n│ Requirements    │ ── Generate/optimize TASK_PROMPT.md\n│ Preprocessing   │\n└─────┬───────────┘\n      │\n      ▼\n┌─────────────────┐\n│ Context Resource│ ── Check data/, examples/ directories\n│ Scanning        │\n└─────┬───────────┘\n      │\n      ▼\n┌─────────────────┐     ┌─────────────────┐\n│ Intelligent     │ ──→ │ Simple: Direct  │\n│ Complexity      │     │ Build           │\n│ Assessment      │     └─────────────────┘\n│                 │     ┌─────────────────┐\n│ Assessment      │ ──→ │ Medium: Design  │\n│ Dimensions:     │     │ + Build         │\n│ • Requirement   │     └─────────────────┘\n│   Clarity       │     ┌─────────────────┐\n│ • Technical     │ ──→ │ Complex: Full   │\n│   Difficulty    │     │ Process         │\n│ • External      │     └─────────────────┘\n│   Dependencies  │\n│ • Material      │\n│   Completeness  │\n└─────────────────┘\n```\n\n## ⚙️ Advanced Configuration\n\n### Custom Agents\n\nCreate custom agents in the `.claude/agents/` directory:\n\n```markdown\n# custom_agent.md\n\n## Role Definition\n[Description of agent's responsibilities and capabilities]\n\n## Workflow\n[Detailed work steps]\n\n## Input/Output\n- Input: [Expected input format]\n- Output: [Output format and content]\n```\n\n### Extension Commands\n\nAdd custom commands in the `.claude/commands/` directory:\n\n```markdown\n# custom_command.md\n\n## Command Description\n/custom - Custom functionality description\n\n## Usage\n[Specific usage of the command]\n\n## Parameter Description\n[Detailed parameter explanations]\n```\n\n### Configuration File\n\nEdit `.claude/settings.local.json` for personalized configuration:\n\n```json\n{\n  \"default_model\": \"claude-3-5-sonnet-20241022\",\n  \"context_window\": 200000,\n  \"temperature\": 0.7,\n  \"custom_settings\": {\n    \"preferred_language\": \"en-US\",\n    \"code_style\": \"standard\",\n    \"documentation_level\": \"detailed\"\n  }\n}\n```\n\n## 📖 Usage Examples\n\n### Example 1: Web Application Development\n\n```bash\n# 1. Prepare requirements\ncat \u003e .contextx/TASK_PROMPT.md \u003c\u003c EOF\n# Blog Management System\n\n## Project Overview\nCreate a simple blog management system supporting CRUD operations for articles.\n\n## Functional Requirements\n- [ ] User registration and login\n- [ ] Article list display\n- [ ] Article detail view\n- [ ] Article editing and publishing\n- [ ] Article deletion\n\n## Technical Requirements\n- Frontend: React + TypeScript\n- Backend: Node.js + Express\n- Database: SQLite\n- Styling: Tailwind CSS\nEOF\n\n# 2. Run generation\nclaude \"/create Blog management system development\"\n```\n\n### Example 2: API Integration Project\n\n```bash\n# 1. Prepare API documentation\nmkdir -p .contextx/data\ncat \u003e .contextx/data/api_docs.md \u003c\u003c EOF\n# Third-party API Documentation\n\n## User API\n- GET /api/users - Get user list\n- POST /api/users - Create user\n- PUT /api/users/:id - Update user\n- DELETE /api/users/:id - Delete user\n\n## Authentication\nBearer Token authentication\nEOF\n\n# 2. Prepare requirements\ncat \u003e .contextx/TASK_PROMPT.md \u003c\u003c EOF\n# User Management Client\n\nBased on the provided API documentation, create a user management frontend application.\nNeed to implement complete CRUD operations with user-friendly interface.\nEOF\n\n# 3. Run generation\nclaude \"/create User management client development\"\n```\n\n## ❓ FAQ\n\n### Q: How to improve the quality of generated code?\nA: \n- Provide detailed requirement descriptions and technical constraints\n- Include relevant API documentation and business rules\n- Provide code examples and reference implementations\n- Clearly specify tech stack and architecture preferences\n\n### Q: What if the generated project doesn't meet expectations?\nA: \n- Check if `.contextx/TASK_PROMPT.md` is clearly described\n- Add necessary technical documentation to the `data/` directory\n- You can iteratively optimize by appending requirements\n- Review the generated `PRC.md` to see if the system understands correctly\n\n### Q: How to handle complex business logic?\nA: \n- Break complex logic into multiple clear functional points\n- Provide business flow charts or state diagrams\n- Include specific business rule documentation\n- Provide code examples of similar business scenarios\n\n## 🤝 Contributing\n\nWe welcome all forms of contributions!\n\n### How to Contribute\n\n1. **Fork the project** and create a feature branch\n2. **Write code** and necessary tests\n3. **Update documentation** to keep it in sync with code\n4. **Submit PR** and describe your changes\n\n### Development Workflow\n\n```bash\n# 1. Clone your fork\ngit clone https://github.com/your-username/ContextX.git\ncd ContextX\n\n# 2. Create feature branch\ngit checkout -b feature/your-feature-name\n\n# 3. Develop\n# ... your code changes\n\n# 4. Commit changes\ngit add .\ngit commit -m \"feat: add your feature description\"\n\n# 5. Push branch\ngit push origin feature/your-feature-name\n\n# 6. Create Pull Request\n```\n\n### Contribution Types\n\n- 🐛 **Bug Fixes**: Fix known issues\n- ✨ **New Features**: Add new functionality\n- 📚 **Documentation Improvements**: Enhance docs and examples\n- 🔧 **Tool Optimization**: Improve development tools and processes\n- 🌐 **Internationalization**: Add multi-language support\n\n## 📜 License\n\nThis project is open source under the [Apache 2.0 License](./LICENSE).\n\n## 🙏 Acknowledgments\n\nThanks to all developers and users who contributed to the project!\n\n**Core Contributors:**\n- [yzfly](https://github.com/yzfly) - Project creator and main maintainer\n\n**Special Thanks:**\n- [Anthropic](https://www.anthropic.com/) for Claude Code technical support\n- All community members who provided feedback and suggestions\n\n## 🔗 Related Links\n\n- **Official Documentation**: [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)\n- **Issue Reports**: [GitHub Issues](https://github.com/yzfly/ContextX/issues)\n- **Feature Requests**: [Feature Request](https://github.com/yzfly/ContextX/issues/new?template=feature_request.md)\n- **Project Discussions**: [GitHub Discussions](https://github.com/yzfly/ContextX/discussions)\n\n## 💬 Community Support\n\n- **WeChat Group**: Add WeChat (1796060717) to join LangGPT exchange group\n- **WeChat Official Account**: 云中江树 (Cloud Tree)\n- **GitHub**: [@yzfly](https://github.com/yzfly)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**If this project helps you, please give it a ⭐️**\n\n[![Star History Chart](https://www.star-history.com/#yzfly/ContextX\u0026Date)](https://www.star-history.com/#yzfly/ContextX\u0026Date)\n\nMade with ❤️ by [yzfly](https://github.com/yzfly)\n\n\u003c/div\u003e","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyzfly%2Fcontextx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyzfly%2Fcontextx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyzfly%2Fcontextx/lists"}