MetaCraft/docs/GETTING_STARTED.md

# 快速开始

本指南介绍 MetaCraft 的设计概念和使用方法。**重要提示**：MetaCraft 是一个纯文档化架构项目，包含设计文档和AI工具脚本描述，不包含任何执行环境或运行服务。所有逻辑实现由外部AI工具完成。

## 项目设置

### 1. 克隆仓库（获取设计文档）
```bash
git clone https://github.com/your-username/metacraft.git
cd metacraft
```

### 2. 了解项目结构
MetaCraft 包含以下设计文档：
- **架构设计** (`docs/ARCHITECTURE.md`)：详细技术架构和组件设计
- **AI工具脚本** (`scripts/`)：描述自动化逻辑的实现方法
- **任务管理** (`meta/todo.md`)：开发任务跟踪和优先级

### 3. 外部工具准备
实际执行需要外部AI工具（如 Claude Code CLI）。请参考相应工具的安装文档。

验证外部工具：
```bash
claude --version
```

## 理解 Prompt 执行设计

### 设计概念
Prompt 执行流程在 `scripts/run-prompt.js` 中描述。这是一个**设计文档**，说明如何：

1. **读取 prompt 文件**：解析 Markdown 格式的 prompt
2. **提取元数据**：识别任务目标、优先级等信息
3. **注入上下文**：为 AI 提供项目状态和相关代码
4. **调用外部 AI 工具**：执行 prompt 并获取响应
5. **解析 AI 输出**：将响应转换为具体操作

### 参考示例
1. **查看示例 prompt**：打开 `prompts/example.md`，这是一个描述创建欢迎脚本任务的设计示例。
2. **理解执行逻辑**：阅读 `scripts/run-prompt.js` 了解 prompt 执行的设计思路。
3. **外部工具实现**：外部 AI 工具应参考此设计来实现实际执行。
4. **预期结果**：设计预期 AI 会生成 `welcome.js` 文件，外部工具可执行该文件。

## 自举开发设计概念

MetaCraft 的核心是自举（bootstrapping）设计——描述如何使用工具自身来开发工具。

### 1. 任务管理设计
- **待办任务格式**：`meta/todo.md` 描述任务跟踪的设计格式
- **优先级系统**：文档化任务分类和优先级映射逻辑
- **状态更新**：描述任务完成标记的设计机制

### 2. Prompt 查找设计
描述如何根据任务描述查找对应 prompt 文件的逻辑：
- 文件名匹配算法
- 目录搜索机制
- 备用路径策略

### 3. 自举循环设计
`scripts/bootstrap.js` 描述自举循环的设计概念：
- 任务列表显示逻辑
- 用户交互设计
- 外部工具调用流程
- 结果验证和状态更新设计

### 4. 设计工作流
1. **设计参考**：阅读 `scripts/bootstrap.js` 了解自举循环设计
2. **外部实现**：AI工具参考此设计实现实际自举功能
3. **验证设计**：按照设计描述的验证步骤检查结果
4. **状态更新**：外部工具应遵循设计中的状态更新逻辑

## 项目结构速查

```
metacraft/
├── prompts/          # 任务prompt设计库
│   └── example.md   # 示例prompt设计
├── scripts/         # AI工具脚本设计文档
│   ├── run-prompt.js # Prompt执行逻辑设计描述
│   ├── bootstrap.js  # 自举循环设计文档
│   └── plan-next.js  # 规划下一步设计文档
├── docs/            # 设计文档
│   ├── ARCHITECTURE.md    # 详细架构设计
│   └── GETTING_STARTED.md # 设计概念快速开始
├── meta/            # 设计元数据
│   └── todo.md      # 设计任务跟踪
├── config/          # 配置设计（暂无）
├── templates/       # 模板设计（暂无）
└── package.json     # 项目元数据（设计依赖参考）
```

## 常见问题

### MetaCraft 项目为什么不包含可执行代码？
MetaCraft 采用纯文档化架构，仅包含设计文档和AI工具脚本描述。实际执行由外部AI工具完成，使得设计知识可移植到不同AI系统。

### 如何使用这些设计文档？
外部AI工具应参考设计文档实现类似功能。例如，Claude Code可以参考 `scripts/run-prompt.js` 中的逻辑描述来实现prompt执行。

### 如何添加新的设计任务？
1. 在 `meta/todo.md` 中添加一行 `- [ ] 任务描述`。
2. 在 `prompts/` 中创建对应的prompt设计文件（可选），描述任务需求和实现方法。

### 如何理解脚本设计文档？
`scripts/` 目录下的文件是**设计描述**，不是可执行代码。它们描述逻辑流程、算法步骤和实现方法，供外部AI工具参考实现。

## 下一步

- 阅读 [ARCHITECTURE.md](ARCHITECTURE.md) 了解详细架构设计。
- 参考 `scripts/` 目录中的设计文档理解实现逻辑。
- 参与设计改进：选择一个待办任务，更新设计文档并提交 Pull Request。