MetaCraft/README.md

# MetaCraft: AI-Powered Meta-Development Tool

## 愿景

MetaCraft 是一个基于AI大语言模型的元开发工具，旨在辅助任意大型项目的开发。其核心思想是：**将软件开发过程转化为一系列可组合、可执行的prompt、脚本和文档**，并通过Claude Code与AI智能体协作，实现项目的迭代构建。

更特别的是，MetaCraft 项目本身也使用这套工具进行开发，形成"自举"（bootstrapping）的闭环，从而验证和优化工具链的有效性。

## 架构理念

MetaCraft 采用**纯文档化架构**：项目仅包含文档、设计说明和AI工具脚本，不包含任何执行环境或运行服务。

- **文档**：Markdown格式的设计文档、架构说明、使用指南
- **设计**：系统组件设计、接口规范、工作流描述
- **工具脚本**：JavaScript文件描述自动化逻辑，供AI参考执行
- **执行分离**：具体执行由外部AI工具（如Claude Code）完成

这种架构使得MetaCraft成为**可移植的知识库**，任何AI系统都可以参考其中的设计来实现类似功能。

## 核心概念

### 1. 开发即对话 (Development as Conversation)
- 每个开发任务都可以表示为一个**prompt**，描述目标、约束和上下文。
- AI（通过Claude Code）理解prompt，并生成或修改代码、文档、脚本。
- 开发者与AI的对话历史成为项目演进的可追溯记录。

### 2. 可执行的知识 (Executable Knowledge)
- **AI工具脚本** 描述自动化操作的逻辑和步骤，供AI参考执行（如文件生成、测试运行、依赖安装）。
- **Markdown 文档** 记录设计决策、架构说明、使用指南，同时也可作为AI的上下文输入。
- **外部AI工具执行** 实际执行由外部AI工具（如Claude Code）完成，本项目不包含执行环境。

### 3. 自举 (Bootstrapping)
- MetaCraft 工具链本身通过MetaCraft定义的工作流进行开发。
- 任何新功能首先被描述为prompt和脚本，然后由AI协助实现，并最终用于增强工具链。
- 这种自举确保工具始终贴近实际开发需求，并能自我改进。

## 架构概述

```
MetaCraft/
├── prompts/          # 任务prompt库
│   ├── project-init.md
│   ├── feature-add.md
│   ├── bug-fix.md
│   └── refactor.md
├── scripts/          # AI工具脚本（供AI参考，不包含执行环境）
│   ├── run-prompt.js   # 执行prompt文件的逻辑描述
│   ├── bootstrap.js    # 自举循环的逻辑描述
│   └── plan-next.js    # 规划下一步的逻辑描述
├── docs/             # 项目文档
│   ├── ARCHITECTURE.md
│   ├── WORKFLOW.md
│   └── SELF-HOSTING.md
├── templates/        # 代码/文件模板
│   └── ...
├── config/           # 配置文件
│   └── default.json
└── meta/             # 工具自身的元数据
    └── manifest.json # 描述工具组件及依赖
```

### 核心组件（设计概念）

1. **Prompt 引擎**：描述如何解析prompt文件，注入上下文变量，调用外部AI工具执行。
2. **脚本执行器**：描述如何运行自动化脚本的逻辑，提供文件操作、Git操作、命令执行等步骤说明。
3. **上下文管理器**：描述如何维护项目状态（如当前模块、依赖关系、待办任务），为AI提供连贯的上下文。
4. **自举循环**：描述一个自举工作流——检测新需求，生成prompt，执行脚本，验证变更。

注意：这些组件是设计概念和逻辑描述，实际执行由外部AI工具完成，本项目不包含执行环境。

## 快速开始

### 前提条件
- 外部AI工具（如Claude Code CLI）用于实际执行
- Git（用于版本控制）
- 注意：本项目不包含执行环境，scripts目录下的脚本是供AI参考的工具描述

### 初始化新项目
```bash
# 使用MetaCraft初始化一个项目（假设已安装meta-cli）
npx meta-cli init my-project
```

### 开发一个功能
1. 在 `prompts/` 下创建一个新的prompt文件，描述功能需求。
2. 让AI参考 `scripts/run-prompt.js` 中的逻辑描述来执行prompt，生成代码草案。
3. 审查生成的代码，运行测试，提交更改。

### 参与MetaCraft自举开发
1. 查看 `meta/todo.md` 获取待开发任务。
2. 选择任务，在 `prompts/` 中编写或更新prompt。
3. 让AI参考 `scripts/bootstrap.js` 中的自举循环逻辑来执行任务。
4. 提交Pull Request。

## 工作流示例

假设要添加一个REST API端点：

1. **任务描述**：创建 `prompts/add-rest-endpoint.md`，描述端点路径、方法、参数、返回类型。
2. **上下文注入**：AI参考项目结构、相关模块的代码片段作为上下文。
3. **AI执行**：外部AI工具（如Claude Code）读取prompt，生成或修改控制器、路由、模型文件。
4. **脚本验证**：AI参考验证逻辑描述来检查语法、运行单元测试。
5. **文档更新**：AI同时更新API文档，记录新端点。

## 贡献指南

MetaCraft 是一个自举项目，欢迎通过以下方式参与：

1. **报告问题**：在GitHub Issues中描述问题或建议。
2. **提交prompt**：改进现有prompt或添加新prompt模板。
3. **增强脚本**：优化自动化脚本，提高可靠性。
4. **文档完善**：补充使用案例、最佳实践。

请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细流程。

## 路线图

### 短期（v0.1）
- [ ] 基础prompt引擎和脚本执行器
- [ ] 简单的自举循环原型
- [ ] 初始化项目模板
- [ ] 基础文档

### 中期（v0.5）
- [ ] 上下文管理器，支持多模块项目
- [ ] 集成测试框架
- [ ] 插件系统，支持自定义脚本和prompt类型
- [ ] 可视化任务看板

### 长期（v1.0）
- [ ] 完整的自举闭环，工具能独立完成大部分自身开发任务
- [ ] 多AI后端支持（Claude, GPT, 本地模型等）
- [ ] 云协作功能，团队共享prompt库和上下文
- [ ] 领域特定扩展（Web, 移动, 嵌入式等）

## 许可证

MIT

## 致谢

本项目受启发于“元编程”、“自举”理念，以及Claude Code等AI辅助开发工具的出现。我们相信，AI与人类协同的软件开发模式将重塑未来的开发工作流。