基于 Claude Code 的 Lights-on 软件工厂脚手架

这是一个用于配合 Claude Code 运行软件工厂（software factory）的起步脚手架。本项目基于为 Votito 开发的架构演进而来；在该架构中，编排器相比于未经优化的 Claude 原生工作流执行方案，节省了约 80% 的 Token 消耗。

快速概览请查阅演讲幻灯片：gojko.net/slides/202609-gotocph.pdf。

本仓库包含哪些内容？

本仓库的目的既是作为新项目的轻量脚手架基础，也是对软件工厂核心概念的教学演示：

本项目提供了以下配置与机制：

1. 安全沙箱/容器环境：用于在安全环境中运行 Claude Code，仅向宿主机共享 workspace 工作区目录。更多信息请参见 CONTAINER.md。
2. 确定性 Bash 命令监管器（Regulator）：用于减少人工审批疲劳，确保 Agent 仅执行项目特定规则允许的命令。该监管器对 Bash 命令进行深度检查，提供自动化批准/拦截，并在拦截时给出替代方案指引。每次 Claude 请求你批准时，你可以让 Claude 添加更多自定义规则。更多信息请参见 REGULATOR.md。
3. 基于 Linter 的确定性反馈系统：用于强制执行特定领域的自定义规范，减少代码审查中的人工介入。通过 PostToolUse 钩子在 Claude 编辑每个 JavaScript 文件时自动运行 Linter，并通过详尽的错误提示引导 Agent 避免常见失误。每当你发现自己在给出重复的架构/代码审查反馈时，都可以让 Claude 编写更多自定义规则；也可以让 Claude 为 HTML/CSS 等其他文件类型实现自定义 ESLint 解析器。更多信息请参见 LINTER-HOOK.md。
4. 基础规划与实现工作流：这是一个刻意保持极简的基础示例，用于演示工作流格式并作为编排器的基础基石。你应该将其替换为你自己的命令或更复杂的业务规则。更多信息请参见 WORKFLOW.md。
5. 确定性多 Agent Claude 工作流脚本生成器：根据实现工作流生成的计划，自动构建 Claude 工作流脚本、编排测试流程与质量门禁（Gates），避免在机械的工作流编排部分浪费大模型推理 Token。它加快了工作流构建速度，将大量常见的编排任务从 LLM 推理层迁移到确定性工具（命令行），既提升了执行速度，又显著削减了 Token 支出。更多信息请参见 ORCHESTRATOR.md。

workspace 目录包含 Claude Code 的相关配置以及一个基础示例项目。

若要配置容器并执行第一次代码变更，请从 GETTING-STARTED.md 开始。

text . ├── README.md this file ├── GETTING-STARTED.md first setup and a first change ├── SETTINGS.md what settings.local.json wires up ├── LINTER-HOOK.md the lint hook and custom lint rules ├── REGULATOR.md the Bash-command regulator ├── ORCHESTRATOR.md how the orchestrator works inside ├── WORKFLOW.md the user flow, from an idea to a finished run ├── CONTAINER.md the container image and the root goals ├── LICENSE ├── makefile container goals: docker-image, init, claude, shell, test, lint, root ├── vm/Dockerfile the container image (Alpine, Node.js, make, git, ...) ├── .gitignore ├── .claude-home/ git-ignored; Claude Code login and history of the container └── workspace/ the project; make claude starts Claude Code here ├── CLAUDE.md includes CONTRIBUTING.md for Claude Code ├── CONTRIBUTING.md workspace layout, commands and rules ├── .claude/ │ ├── settings.local.json hooks, env, permissions, preferences │ ├── agents/ workflow-worker, workflow-gate, workflow-check │ ├── commands/ impact-analysis, plan-execution, execute, regulator │ └── workflow/ │ ├── README.md plan notation and generator reference │ ├── package.json {"type": "module"} for the tooling │ ├── bin/ hook entries and command-line tools │ ├── src/ │ │ ├── regulator/ regulator engine, rules.js, rules/ │ │ ├── generator/ plan validator and workflow generator │ │ ├── lint/ eslint plugin, two rules, lint hook logic │ │ └── transient-dir.js │ └── tests/ tests for all of the tooling ├── plans/ plans, sidecars and progress records ├── src/format-greeting.js sample module (replace it) ├── tests/format-greeting.test.js ├── eslint.config.js ├── makefile init, test, lint and the two workflow gate goals ├── package.json ├── package-lock.json └── .gitignore

• GETTING-STARTED.md — 入门指南：配置容器、启动 Claude Code 并运行首次变更。
• SETTINGS.md — 详解 workspace/.claude/settings.local.json 中的钩子、环境变量、权限与偏好设置。
• LINTER-HOOK.md — 编辑时 Lint 钩子、两个示例规则以及如何编写自定义规则。
• REGULATOR.md — 监管器的决策逻辑、角色分类、核心规则、决策诊断、配置方法与规则扩展。
• WORKFLOW.md — 用户交互全流程：/impact-analysis、/plan-execution、/execute、监视与恢复运行状态、/regulator，以及完整实战案例。
• ORCHESTRATOR.md — 编排器内部运作机制：各组成部件、可执行脚本、各类 Agent、Gate 门禁目标、执行进度管理与断点续跑。
• CONTAINER.md — 容器镜像说明、根目录 Make 目标、挂载卷、覆盖配置、将 node_modules 隔离保存在容器内部的方法及故障排查。
• workspace/.claude/workflow/README.md — 计划表示法、运行结构形态、响应 Schema 与错误故障清单。

遵循 MIT 协议。详见 LICENSE。

Lights-on software factory boilerplate for Claude Code

A starting point for running a lights-on software factory with Claude Code. Based on the setup developed for Votito, where the orchestrator reduced token spend compared to bare-bones Claude workflow execution by around 80%.

See gojko.net/slides/202609-gotocph.pdf for a quick overview.

What is in this repostory?

The purpose of this repository is to act both as a simple boilerplate setup for new projects, and as an educational demonstration of the core concepts of software factories:

This repository provides setup for:

1. A sandbox/container for running Claude Code in a secure environment, sharing only the workspace directory with the host. See CONTAINER.md for more information.
2. A deterministic bash command regulator, to reduce approval fatigue and ensure agents execute the commands allowed by project-specific rules. The regulator performs a deep-inspection of bash commands and provides automated approve/deny with instructions on what to do instead if blocked. See REGULATOR.md for more information. Ask Claude to add more custom rules each time it asks you for approval.
3. A deterministic linter-based feedback system for enforcing custom domain-specific rules, to help reduce human involvement in code review. A PostToolUse hook runs the linter on every JavaScript file Claude edits, and guides the agents to avoid common mistakes with helpful error messages. Ask Claude to write more custom rules each time you find yourself providing repetitive design/code feedback. Ask Claude to implement custom eslint language parsers for HTML/CSS/other file types. See LINTER-HOOK.md for more information.
4. A basic planning/implementation workflow. This is a trivial example intentionally kept simple to demonstrate the format and serve as a foundation for the orchestrator. You should probably replace it with your own commands or more complex rules. See WORKFLOW.md for more information.
5. A deterministic multi-agent Claude workflow script generator. Based on the plan produced by the implementation workflow, it creates Claude workflow scripts, structures testing and gates and avoids wasting inference tokens on the mechanical part of workflow orchestration. It speeds up workflow creation and moves many common workflow orchestration tasks from inference (LLM) to deterministic tools (command-line) speeding them up and significantly reducing token spend. See ORCHESTRATOR.md for more information.

The workspace directory contains Claude code setup and a trivial example project.

To set up the container and run a first change, start with GETTING-STARTED.md.

.
├── README.md                    this file
├── GETTING-STARTED.md           first setup and a first change
├── SETTINGS.md                  what settings.local.json wires up
├── LINTER-HOOK.md               the lint hook and custom lint rules
├── REGULATOR.md                 the Bash-command regulator
├── ORCHESTRATOR.md              how the orchestrator works inside
├── WORKFLOW.md                  the user flow, from an idea to a finished run
├── CONTAINER.md                 the container image and the root goals
├── LICENSE
├── makefile                     container goals: docker-image, init, claude, shell, test, lint, root
├── vm/Dockerfile                the container image (Alpine, Node.js, make, git, ...)
├── .gitignore
├── .claude-home/                git-ignored; Claude Code login and history of the container
└── workspace/                   the project; `make claude` starts Claude Code here
    ├── CLAUDE.md                includes CONTRIBUTING.md for Claude Code
    ├── CONTRIBUTING.md          workspace layout, commands and rules
    ├── .claude/
    │   ├── settings.local.json  hooks, env, permissions, preferences
    │   ├── agents/              workflow-worker, workflow-gate, workflow-check
    │   ├── commands/            impact-analysis, plan-execution, execute, regulator
    │   └── workflow/
    │       ├── README.md        plan notation and generator reference
    │       ├── package.json     {"type": "module"} for the tooling
    │       ├── bin/             hook entries and command-line tools
    │       ├── src/
    │       │   ├── regulator/   regulator engine, rules.js, rules/
    │       │   ├── generator/   plan validator and workflow generator
    │       │   ├── lint/        eslint plugin, two rules, lint hook logic
    │       │   └── transient-dir.js
    │       └── tests/           tests for all of the tooling
    ├── plans/                   plans, sidecars and progress records
    ├── src/format-greeting.js   sample module (replace it)
    ├── tests/format-greeting.test.js
    ├── eslint.config.js
    ├── makefile                 init, test, lint and the two workflow gate goals
    ├── package.json
    ├── package-lock.json
    └── .gitignore

• GETTING-STARTED.md — start here: set up the container, start Claude Code and run a first change.
• SETTINGS.md — the hooks, environment, permissions and preferences in workspace/.claude/settings.local.json.
• LINTER-HOOK.md — the lint-on-edit hook, the two example rules and how to write a rule.
• REGULATOR.md — how the regulator decides, the roles, the notable rules, diagnosing a decision, configuring it and adding a rule.
• WORKFLOW.md — the user flow: /impact-analysis, /plan-execution, /execute, watching and resuming a run, /regulator, and a worked example.
• ORCHESTRATOR.md — how the orchestrator works inside: the pieces, the bins, the agents, the gate goals, progress and resume.
• CONTAINER.md — the container image, the root goals, mounts, overrides, keeping node_modules in the container, troubleshooting.
• workspace/.claude/workflow/README.md — the plan notation, the run shape, the answer schemas and the fault list.

MIT. See LICENSE.