# rule

**Repository Path**: lix-codes/rule

## Basic Information

- **Project Name**: rule
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-20
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI-First Harness

这套工具是一个 AI Coding 项目工厂：它创建能让 Coding Agent 直接在受管边界内签入代码的项目，同时用机器可判定的规则阻止越界。它只做两件事：

- `create` —— 向一个**不存在的目录**原子地发布一个完整项目（同卷 staging + rename，中途失败零残留）。
- `check` —— **只读**地校验项目的 managed 文件与生成器蓝图一致，报告 drift。

它不做的事：单调包维护 `update`、事务 journal/回滚/锁链、manifest 所有权账本、spec 生命周期、以及任何"先读 spec / 先写失败测试 / 不得弱化验证"的流程纪律。写代码的流程是你和 Coding Agent 的事，生成器只保证机器边界。

生成器入口：

```powershell
$Harness = 'C:\A-codes\lix\rule\create-harness.mjs'
```

## 新项目

### TypeScript

```powershell
$Project = 'C:\A-codes\lix\my-new-ts-project'
node $Harness create $Project --lang ts
Set-Location $Project
pnpm install --frozen-lockfile
pnpm verify
node $Harness check .
```

### Python

目录名可以带连字符，但 `--pkg` 必须是合法 Python 标识符：

```powershell
$Project = 'C:\A-codes\lix\my-new-python-service'
node $Harness create $Project --lang python --pkg my_new_python_service
Set-Location $Project
python -m venv .venv
& .\.venv\Scripts\python.exe -m pip install --disable-pip-version-check pip==26.1.1
& .\.venv\Scripts\python.exe -m pip install -r requirements-dev.lock
& .\.venv\Scripts\python.exe -m pip install --no-build-isolation --no-deps -e .
& .\.venv\Scripts\python.exe scripts\verify.py
node $Harness check .
```

`create` 只接受不存在的目录；目标已存在时返回退出码 2 并零写入。创建后第一次完整 `verify` 是绿色基线。

> 运行时/安装器在 `harness/policy.mjs` 里声明"已验证兼容区间"（node `>=24 <25`、python `>=3.13,<3.14`、pnpm/pip 区间），并保留一个具体测试点；生成项目内的依赖锁（`requirements-dev.lock` / `pnpm-lock.yaml`）由模板作者维护精确版本，生成器不做单点硬性校验。

## 日常任务

1. 从仓库根目录启动 Coding Agent。Codex 自动读取 `AGENTS.md`，Claude Code 自动读取 `CLAUDE.md`；目录级同名文件只补充当前位置的约束。
2. 让 Agent 在受管边界内完成测试与实现，保持边界检查通过。
3. 人工确认项目完整 `verify` 通过：TypeScript 是 `pnpm verify`，Python 是 `python scripts/verify.py`。

`verify` 里内置一道**自包含门禁完整性校验**（TS `scripts/check-managed.mjs` / Python `scripts/check_managed.py`，对照 `.harness/managed.map.json`）：它会拦截"删测试 / 改短 `verify` / 改 CI 凑绿"。因此 Agent 把门禁改没这事，**不需要生成器在场**也能在 CI 里被机器堵死——这是"AI 可验证"的关键兜底。合入前请确保两步都绿：`verify` 通过 且 运行一次 `check` 确认 managed 层无 drift。
4. 运行 `node $Harness check .`，确认 managed 层没有 drift。

## 文件分别负责什么

| 文件 | 作用 |
|---|---|
| `harness/policy.mjs` | 生成器内唯一机器 SSOT；规则、依赖矩阵、工具链都从这里派生 |
| `.harness/policy.json` | `check` 的身份来源（language / packageName / templateVersion）；规则总是由运行时加载的生成器重建，不靠它固定 |
| `docs/ARCHITECTURE.md` | 面向人的架构说明 |
| `docs/HARNESS.md` | 生成项目内的使用说明 |
| `AGENTS.md` / `CLAUDE.md` | Codex 与 Claude 的入口；目录级同名文件补充增量约束 |

规则要改在本仓库的 `harness/policy.mjs`，运行生成器测试后，用 `create` 重建示例项目。不要直接改生成项目的 policy 快照或 Agent 入口。

## managed 与 create-only

- `managed`（守卫）是门禁体系本身 + 规则文档：`verify`/CI 配置、`check-managed`/`check-layout`/`check_boundaries`/`verify` 脚本、边界契约测试、`policy.json`、各 `AGENTS.md`/`CLAUDE.md`、`docs/`。`check` 对比磁盘与生成器预期，改动即 drift。
- `create-only`（归你主宰）是构建/栈配置 + 示例业务，创建后归项目所有，可自由修改删除，`check` 不再管。TS 含 `package.json`、`pnpm-lock.yaml`、`tsconfig.json`、`eslint.config.js`、`vitest.config.ts`、`.dependency-cruiser.cjs`；Python 含 `pyproject.toml`、`requirements-dev.lock`。

因此修改业务 seed、**加依赖、换框架（如 vue/react）或改构建配置只动 create-only 文件，永不触发 drift**；改受管门禁/规则入口才会被 `check` 拦。

## 命令、退出码与恢复

| 退出码 | 含义 | 下一步 |
|---:|---|---|
| 0 | 成功或 check clean | 继续或提交 |
| 1 | check 发现 managed drift | 审查改动，必要时对照生成器预期修复 |
| 2 | create 目标已存在 | 删除目标或换路径 |
| 64 | 命令参数错误 | 修正 command、`--lang`、`--pkg` |
| 65 | `.harness/policy.json` 缺失或无效 | 确认这是一个由当前 harness create 的项目 |
| 74 | 未分类软件或 IO 错误 | 保留完整错误输出排查 |

```powershell
node create-harness.mjs create <target> --lang ts|python [--pkg <name>]
node create-harness.mjs check <target>
```

- `check` 永远只读，不写任何目标文件；它对比每个 managed 文件的哈希与执行位。
- 没有 `update`、没有 `--dry-run`、没有 `--force`、没有事务锁。这是有意的减法：生成器只对"新建"写入，对"校验"只读。
- 若 `.harness` 缺失或 `policy.json` 损坏，`check` 返回 65；先 `create` 到新目录，或从干净来源恢复。
- **一次性**：项目由 `create` 一次生成，没有原地升级。生成器升级后受管文件保持旧版，`check` 会因版本不一致打印 `[NOTICE]` 并可能整体 drift；要吸收升级需重建并手迁业务代码。
- **`check` 依赖生成器在场**才能运行（重建蓝图）；离线接收方无法再 `check`，但不影响项目正常提交/构建/运行。

Windows 下可双击 `create-harness.cmd` 进入菜单（新建 / 检查），带参数时直接透传 CLI。

## 生成器自身验证

修改 `harness/`、renderer、policy 或模板后，在本目录运行：

```powershell
node --test "tests/*.test.mjs" "tests/evals/*.test.mjs"
```

生成器测试、TS/Python clean-room verify 都通过后，才用 `create` 重建示例项目。

## 如何打包带走

### 带走 Harness 生成器本身

运行生成器只需要 Node.js。最小必需文件是：

```text
create-harness.cmd       # Windows 交互入口，可选但推荐
create-harness.mjs       # Node 入口
harness\                 # 必须整体携带，不能只复制其中一个文件
```

`README.md` 建议一起带。`tests\`、`tests\evals\`、`py-harness\` 和缓存目录都不是运行生成器所必需的。

在当前目录打包生成器：

```powershell
Compress-Archive -Path create-harness.cmd,create-harness.mjs,harness,README.md `
  -DestinationPath ai-first-harness.zip -Force
```

### 带走已经生成的业务项目

生成项目本身不依赖生成器目录；可以独立提交 Git 或压缩传输。打包前先在项目根目录运行 `node C:\path\to\create-harness.mjs check .` 确认 clean。必须保留：

```text
.harness\policy.json     # check 的身份来源
AGENTS.md / CLAUDE.md    # Agent 入口
docs\                    # ARCHITECTURE.md、HARNESS.md
scripts\                 # verify 和边界检查器
package.json + pnpm-lock.yaml       # TypeScript
pyproject.toml + requirements-dev.lock  # Python
.*version、.gitattributes、.gitignore、CI 配置
src\、tests\              # 业务源码和测试
```

以下目录可不打包，接收方重装：`node_modules\`、`.venv\`、`__pycache__\`、`.pytest_cache\`、`.mypy_cache\`、`.ruff_cache\`、`coverage\`、`dist\`。

## 示例项目

`py-harness/` 是一个由当前生成器 `create` 的最小 Python 示例（`--pkg py_harness`），`check` 确认其 managed 层与蓝图一致。