AI-Powered Human-in-the-Loop Development Framework

简体中文 | English

Features • Installation • Architecture • Commands • Contributing

---

Features

🚀 Fully Autonomous Development

With complete PRD and comprehensive tech specs, the entire development process runs autonomously - no human attendance required. Just set it up and let it run.

🔄 Human-in-the-Loop

Human-in-the-loop design philosophy - AI executes, humans decide. Every critical node can pause for human intervention, ensuring controllable and predictable development.

🛠️ Harness Architecture

Extensible Agent framework - Orchestrator, Coder, Tester, Fixer, Reviewer - five specialized agents collaborate through state files to drive the development loop.

⚡ Dual Engine Support

Supports both OpenCode and Claude Code, switch AI engine with one command.

🌐 Tech Stack Agnostic

Java/Spring Boot, Python, Node.js, React, Vue... Any tech stack, just define tech-stack.md to start.

---

Installation

Prerequisites

• Python 3.8+
• OpenCode or Claude Code installed

OpenCode Installation

Windows:

scoop install opencode
# or
npm install -g opencode-ai

macOS:

brew install anomalyco/tap/opencode
# or
npm install -g opencode-ai

Linux:

curl -fsSL https://opencode.ai/install | bash
# or
npm install -g opencode-ai

Claude Code Installation

npm install -g @anthropic-ai/claude-code
claude auth login

HarnessCode Installation

Windows:

python -m pip install --upgrade pip
python -m pip install -e .
hc --version

macOS / Linux:

python3 -m pip install --upgrade pip
python3 -m pip install -e .
hc --version

🔧 Common Issues

Q: hc command not found

Windows: Add Python Scripts directory to PATH

python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
# Add the output path to system PATH

macOS/Linux:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Q: externally-managed-environment error

Use venv:

python3 -m venv ~/.hc-venv
source ~/.hc-venv/bin/activate
pip install harnesscode

---

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Orchestrator                         │
│         Read State → Decide Next → Dispatch Agent       │
└─────────────────────┬───────────────────────────────────┘
                      │
        ┌─────────────┼─────────────┐
        │             │             │
        ▼             ▼             ▼
┌───────────┐  ┌───────────┐  ┌───────────┐
│  Coder    │  │  Tester   │  │  Fixer    │
│  Implement│  │   Test    │  │   Fix     │
└───────────┘  └───────────┘  └───────────┘
        │             │             │
        └─────────────┼─────────────┘
                      │
                      ▼
              ┌───────────┐
              │ Reviewer  │
              │  Review   │
              └───────────┘

Agent Responsibilities

Agent	Responsibility
Orchestrator	Read project state, decide which agent to run next
Initializer	Project setup, check tech stack, generate feature_list
Coder	Implement feature code
Tester	Multi-layer testing: static analysis → unit test → compilation
Fixer	Fix issues based on test/review reports
Reviewer	Code compliance review

State Files

.your-project/
├── .harnesscode/                 # Runtime data (auto-generated)
│   ├── feature_list.json         # Feature list
│   ├── test_report.json          # Test report
│   ├── review_report.json        # Review report
│   ├── missing_info.json         # Blockers (need human action)
│   └── config.yaml               # Project config
├── input/                        # Input files
│   ├── prd/                      # PRD documents
│   │   └── tech-stack.md         # Tech stack definition (required)
│   └── techspec/                 # Tech spec files
└── dev-log.txt                   # Runtime log

Input Files

input/prd/ - PRD Documents

Contains product requirements and tech stack definition.

File	Required	Description
tech-stack.md	✅ Yes	Tech stack definition. Filename must be exact, format is flexible

The included tech-stack.md is an example (Java + React). Customize it for your project.

input/techspec/ - Tech Spec Files

Code conventions and standards. Each file defines rules for a specific category.

Java Specs (use as reference or modify directly):

• tech-spec-checkstyle.md - Code style (Checkstyle)
• tech-spec-entity.md - Entity class conventions
• tech-spec-dto.md - DTO conventions
• tech-spec-service.md - Service layer conventions
• tech-spec-controller.md - Controller conventions
• tech-spec-mapper.md - MyBatis Mapper conventions
• tech-spec-enum.md - Enum conventions
• tech-spec-exception.md - Exception handling
• tech-spec-response.md - API response format
• tech-spec-database.md - Database conventions

React/TypeScript Specs:

• tech-spec-react-component.md - React component conventions
• tech-spec-typescript.md - TypeScript conventions
• tech-spec-antd-usage.md - Ant Design usage
• tech-spec-api-request.md - API request conventions
• tech-spec-frontend-*.md - Frontend routing, style, form, performance, security
• tech-spec-redux.md - State management
• tech-spec-i18n.md - Internationalization

---

Commands

Command	Description
hc init	Initialize project config (interactive)
hc start	Start development loop
hc status	Show project status and metrics
hc restore	Restore config files from backup
hc uninstall	Uninstall HarnessCode
hc --version	Show version info

Options

hc init --backend claude    # Use Claude Code engine
hc start --backend opencode # Use OpenCode engine

---

Environment Variables

Variable	Description
HARNESSCODE_BACKEND	Default AI engine (opencode/claude)
OPENCODE_PATH	Custom opencode command path
CLAUDE_PATH	Custom claude command path

---

Project Structure

harnesscode/
├── pyproject.toml          # Package config
├── src/harnesscode/
│   ├── cli.py              # CLI entry
│   ├── infinite_dev.py     # Main loop script
│   ├── installer.py        # Init/uninstall module
│   ├── backend.py          # AI engine abstraction
│   ├── agents/             # Agent definitions
│   │   ├── orchestrator.md
│   │   ├── initializer.md
│   │   ├── coder.md
│   │   ├── tester.md
│   │   ├── fixer.md
│   │   └── reviewer.md
│   └── utils/              # Utility modules
└── input/                  # Input file examples

---

Uninstall

# Clean agent files and config
hc uninstall

# Uninstall Python package
pip uninstall harnesscode

---

Contributing

Contributions welcome! See Contributing Guide.

Development

git clone https://github.com/yzddp/harnesscode.git
cd harnesscode
python -m pip install -e .

---

License

MIT

---

Made with ❤️ by 油炸电灯泡 (yzddp)