admin123
/
MetaCraft
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
MetaCraft/CLAUDE.md

9.9 KiB
Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MetaCraft is an AI-powered meta-development tool that transforms software development into a series of composable, executable prompts, scripts, and documents. The project adopts a documentation-only architecture - containing only documents, designs, and AI tool scripts, with no execution environment or runtime services. External AI tools execute the logic described in these scripts.

Common Commands

Development Workflow (AI Tool Reference)

These commands describe how an external AI tool should execute development workflows. The scripts in this project are tool descriptions for AI reference, not executable code.

# How to execute the bootstrap loop logic (self-development cycle)
# Reference: scripts/bootstrap.js for detailed steps
# External AI tool should implement: read todo.md, show tasks, execute prompts

# How to execute a specific prompt file
# Reference: scripts/run-prompt.js for detailed steps
# External AI tool should implement: read prompt file, extract metadata, call Claude Code

# How to plan the next development step
# Reference: scripts/plan-next.js for detailed steps
# External AI tool should implement: analyze project state, recommend tasks, generate files

# View current todo tasks
cat meta/todo.md

Testing (Design Concept)

# Testing framework design - to be implemented by external AI tools
# Reference: docs/ARCHITECTURE.md for testing strategy design

Installation (Project Setup)

# This project requires no installation - it's a documentation and design repository
# Clone the repository and explore the documentation
git clone <repository-url>
cd MetaCraft

Code Architecture

Core Components (Design Concepts)

1. Prompt Engine Design (scripts/run-prompt.js)

  • Describes how to parse Markdown-based prompt files
  • Explains metadata extraction (target, priority, etc.)
  • Outlines context injection (project structure, git status)
  • Provides guidance on calling external AI tools
  • Documents response parsing into actionable operations

2. Bootstrap Loop Design (scripts/bootstrap.js)

  • Describes reading todo list from meta/todo.md
  • Explains user interaction for task selection
  • Documents prompt file lookup logic
  • Outlines prompt execution steps via external tools
  • Provides task status update procedures

3. Plan Next Step Design (scripts/plan-next.js)

  • Describes project state analysis (completed vs pending tasks)
  • Documents task recommendation algorithms based on priority and category
  • Explains prompt file generation logic
  • Outlines next-step planning document creation

4. Context Manager Design (conceptual)

  • Describes project state maintenance strategies
  • Documents context provision techniques for AI during prompt execution
  • Explains dependency tracking and change history management

Note: These are design documents for AI reference, not executable code.

Directory Structure

MetaCraft/
├── prompts/          # Prompt library for tasks
│   └── example.md   # Example: creates welcome.js
├── scripts/          # AI tool scripts (design documents, not executable)
│   ├── run-prompt.js   # Prompt execution logic description
│   ├── bootstrap.js    # Bootstrap loop design document
│   └── plan-next.js    # Next-step planning design document
├── docs/             # Project documentation
│   ├── ARCHITECTURE.md    # Detailed architecture design
│   ├── GETTING_STARTED.md # Quick start guide
│   └── next-steps/    # Auto-generated next step plans
├── meta/             # Tool metadata
│   └── todo.md      # Pending development tasks
├── config/           # Configuration (currently empty)
├── templates/        # File templates (currently empty)
├── package.json      # Project metadata (dependencies are design references)
└── README.md         # Project overview and architecture

Key Files

Task Management

  • meta/todo.md: Markdown task list tracking all pending work
    • Categorized by: Core功能开发, 基础设施, 文档, 测试与质量, 未来功能
    • Tasks are checked off as they're completed
    • Bootstrap loop automatically updates this file

Prompt Format

Prompts use Markdown with special metadata blocks:

<!-- target: task-name -->
<!-- priority: high|medium|low -->

## 描述
Task description in detail.

## 上下文
Auto-injected project context

## 输出要求
Expected deliverables

Scripts (AI Tool Descriptions)

  • run-prompt.js: Describes how to execute a prompt file - file validation, metadata extraction, external AI tool invocation
  • bootstrap.js: Documents the self-development loop logic - task listing, user interaction, prompt execution, status updates
  • plan-next.js: Outlines project state analysis and next-step planning - task recommendation algorithms, file generation procedures

Development Workflow

Bootstrapping Process (Design Logic)

  1. View pending tasks: Read meta/todo.md
  2. Bootstrap loop logic: Reference scripts/bootstrap.js for implementation steps
  3. Select a task number: User interaction design
  4. Find corresponding prompt file: File lookup algorithm in prompts/ directory
  5. Execute prompt: Call external AI tool (e.g., Claude Code) following scripts/run-prompt.js guidelines
  6. Review AI-generated output: Result processing and validation
  7. Mark task as complete: Update meta/todo.md status

Adding New Tasks (Design Logic)

  1. Edit meta/todo.md and add a new unchecked task: - [ ] Task description
  2. Create corresponding prompt file in prompts/ (optional)
    • Filename should relate to task (e.g., implement-prompt-engine.md)
  3. Execute via bootstrap loop logic: Reference scripts/bootstrap.js for implementation

Planning Next Steps (Design Logic)

  1. Analyze project state: Reference scripts/plan-next.js for recommendation algorithms
  2. Choose an action: generate prompt file, planning document, or both
  3. Review generated files and adjust as needed
  4. Execute the task: Use external AI tools following the described logic

Example: Running the Example Prompt (Design Logic)

# How to execute the example prompt:
# 1. Reference scripts/run-prompt.js for execution logic
# 2. Read prompts/example.md for prompt content
# 3. Call external AI tool to execute the prompt

# Expected outcome:
# - AI generates welcome.js with timestamped welcome message
# - External tool can then execute welcome.js

Dependencies (Design References)

Design Dependency Descriptions

  • commander: CLI argument parsing design pattern reference
  • fs-extra: Enhanced file system operation design patterns
  • marked: Markdown parsing design approach
  • simple-git: Git operation design patterns

Implementation Requirements

  • External AI Tool: For actual execution (e.g., Claude Code, other AI assistants)
  • File System Access: Required by external tools to read project files
  • Git: For version control of the design documents

Note: This project contains no runtime dependencies or execution environment. The dependencies listed are design references describing how external tools should implement similar functionality.

Important Notes

Architecture Philosophy

MetaCraft follows a documentation-only architecture:

  • No execution environment: Scripts are design documents, not executable code
  • External tool execution: All logic is implemented by external AI tools (e.g., Claude Code)
  • Portable knowledge: Designs can be referenced by any AI system
  • Self-development concept: The toolchain describes how to develop itself

Current Implementation Status

  • Design documents complete: Bootstrap loop, prompt execution, and planning logic are fully documented
  • No runtime components: Core components (prompt-engine, script-runner, context-manager) exist only as design concepts
  • Pure documentation: All scripts are descriptive, not functional
  • Version: Design phase v0.0.1

Prompt Execution (Design Concept)

  • External tool requirement: Execution requires external AI tools, not built-in runtime
  • Logic description: scripts/run-prompt.js describes how to validate, extract metadata, and invoke AI tools
  • Temporary files: Design includes .temp/ directory concept for intermediate files

File Generation (Design Concept)

  • AI-generated artifacts: Prompts can describe file generation (e.g., welcome.js from example)
  • Git integration: Generated files would be gitignored in actual implementations

Self-Development (Design Concept)

This project describes a self-development methodology. The bootstrap loop design:

  1. Describes reading tasks from meta/todo.md
  2. Documents executing corresponding prompts via external tools
  3. Outlines AI code generation and modification processes
  4. Provides status update procedures

This creates a design for a closed loop where tools could theoretically improve themselves.

Documentation

This project consists entirely of design documentation and AI tool descriptions:

Core Design Documents

  • README.md: Project vision, architecture philosophy, and overview
  • docs/ARCHITECTURE.md: Detailed technical architecture design and component specifications
  • docs/GETTING_STARTED.md: Design implementation guide and conceptual setup

Development Planning

  • meta/todo.md: Design task tracking and development priorities
  • docs/next-steps/: Auto-generated next-step planning documents (design concepts)

AI Tool Scripts (Design References)

  • scripts/run-prompt.js: Prompt execution logic description
  • scripts/bootstrap.js: Bootstrap loop design document
  • scripts/plan-next.js: Next-step planning design document

All content is design documentation meant to be referenced by external AI tools for implementation guidance.