harper-local-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Harper Local Development

Harper 本地开发

Guidelines for running and managing Harper on a developer machine. Where

harper-best-practices

covers how to build a Harper application, this skill covers the environment you build it in: how dev instances are started, isolated from one another, and cleaned up.

在开发者机器上运行和管理Harper的指南。

harper-best-practices

介绍的是如何构建Harper应用，而本技能介绍的是构建应用的环境：开发实例如何启动、如何相互隔离以及如何清理。

When to Use

何时使用

Reference these guidelines when:

Running more than one Harper dev instance on the same machine (one per git worktree, branch, or agent session)
Diagnosing
```
EADDRINUSE
```
on Harper's default ports, or a dev server that reloads in a loop
Setting up a project's
```
npm run dev
```
so that it is safe to run in parallel
Pointing tooling (agents, browsers, test scripts) at the right dev instance for the current worktree
Letting a sandboxed AI agent (e.g. Claude Code with the sandbox enabled) start and reach a dev instance

在以下场景中可参考本指南：

在同一台机器上运行多个Harper开发实例（每个git worktree、分支或Agent会话对应一个实例）
排查Harper默认端口的
```
EADDRINUSE
```
错误，或开发服务器循环重载的问题
配置项目的
```
npm run dev
```
命令，使其可安全地并行运行
将工具（Agent、浏览器、测试脚本）指向当前worktree对应的正确开发实例
让沙箱化的AI Agent（例如启用了沙箱的Claude Code）启动并访问开发实例

How It Works

工作原理

Identify the shared state two Harper processes would contend for (ports, data root, file watcher).
Consult the relevant rule under "Quick Reference" below and read its rule file.
Prefer the ready-to-copy scripts under
```
scripts/
```
over writing your own wrapper.

识别两个Harper进程会争抢的共享资源（端口、数据根目录、文件监听器）。
查阅下方「快速参考」中的相关规则，并阅读对应的规则文件。
优先使用
```
scripts/
```
目录下可直接复用的脚本，而非自行编写封装脚本。

Examples

示例

See the concrete examples embedded in each rule (wrapper scripts,

package.json

wiring, and debugging commands), plus the reference implementations in

scripts/

可查看每条规则中附带的具体示例（封装脚本、

package.json

配置、调试命令），以及

scripts/

目录下的参考实现。

Rule Categories by Priority

按优先级划分的规则类别

Priority	Category	Impact	Prefix
1	Dev Instances	HIGH	`dev-`

优先级	类别	影响程度	前缀
1	开发实例	高	`dev-`

Quick Reference

快速参考

1. Dev Instances (HIGH)

1. 开发实例（高优先级）

```
running-dev-instances-in-worktrees
```
— Run multiple Harper dev instances in parallel from git worktrees with isolated data roots and loopback addresses.

```
running-dev-instances-in-worktrees
```
— 从git worktree并行运行多个Harper开发实例，具备隔离的数据根目录和回环地址。

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/running-dev-instances-in-worktrees.md

请阅读各规则文件获取详细说明和代码示例：

rules/running-dev-instances-in-worktrees.md

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需包含所有规则的完整指南，请查看：

AGENTS.md