initial: hanarang-rails 프로젝트 스켈레톤
기존 hanarang-harness의 결정성 문제를 해결하기 위한 후계작. 강제 기반 결정론 파이프라인으로 전면 재설계. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
1
.claude/sessions/.last_inbox_check
Normal file
1
.claude/sessions/.last_inbox_check
Normal file
@@ -0,0 +1 @@
|
||||
1775791299
|
||||
38
.gitignore
vendored
Normal file
38
.gitignore
vendored
Normal file
@@ -0,0 +1,38 @@
|
||||
# Dependencies
|
||||
node_modules/
|
||||
.pnpm-store/
|
||||
|
||||
# Build output
|
||||
dist/
|
||||
build/
|
||||
*.tsbuildinfo
|
||||
|
||||
# Test
|
||||
coverage/
|
||||
.vitest-cache/
|
||||
|
||||
# Runtime state
|
||||
data/
|
||||
*.db
|
||||
*.db-journal
|
||||
*.db-wal
|
||||
logs/
|
||||
*.log
|
||||
|
||||
# Environment
|
||||
.env
|
||||
.env.local
|
||||
.env.*.local
|
||||
!.env.example
|
||||
|
||||
# Editor
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
.DS_Store
|
||||
|
||||
# Claude Code
|
||||
.claude/state/
|
||||
.claude/logs/
|
||||
.claude/agent-memory/
|
||||
21
LICENSE
Normal file
21
LICENSE
Normal file
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 나봄하랑 (Nabomhalang)
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
81
README.md
Normal file
81
README.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# hanarang-rails
|
||||
|
||||
> **4자매가 달릴 결정론적 레일** — HaNaRang Rails
|
||||
|
||||
`hanarang-harness`의 후계작. 기존 하네스가 "권고 기반 파이프라인"이라 자매들이 레일을 벗어나 끊기고 엇갈리던 문제를 **강제 기반 결정론 파이프라인**으로 재설계한다.
|
||||
|
||||
## 왜 다시?
|
||||
|
||||
[`hanarang-harness`](https://git.nabomhalang.co.kr/hanarang/openclaw-harness)에서 발견된 6가지 실패 모드:
|
||||
|
||||
| 코드 | 증상 | 원인 |
|
||||
|---|---|---|
|
||||
| F1 | 하네스 skill bypass — 자매가 worker 혼자 스폰하고 처리 | skill 진입 강제 없음 |
|
||||
| F2 | DoD 자동 강제 실패 — build 통과 = 완료로 간주 | sprint contract / validator 없음 |
|
||||
| F3 | QA 단계 누락 — 사용자가 수동으로 다랑이 호출 | 자동 라우팅 없음 |
|
||||
| F4 | 핸드오프 멘션 불안정 — 잘못된 자매 호출 | Lobster 분기가 LLM에 의존 |
|
||||
| F5 | 중간 끊김 — request-timed-out 반복, xhigh 무한대기 | 재시도/fallback 정책 없음 |
|
||||
| F6 | 환경 검증 누락 — "서버에 Docker 없음" 으로 skip 용인 | 환경 전제 검사 없음 |
|
||||
|
||||
## 6가지 원칙
|
||||
|
||||
1. **결정론적 라우터** — LLM 판단이 아니라 XState FSM으로 자매 간 전이
|
||||
2. **Sprint Contract 강제** — DoD를 Zod 스키마로 정의, validator가 pass/fail 판정
|
||||
3. **Skill 강제 진입** — skill bypass를 hook으로 감지해 차단
|
||||
4. **상태 전이 기반 핸드오프** — 멘션은 사용자 알림 전용, 자매 간 통신은 FSM 상태
|
||||
5. **재시도/에스컬레이션** — timeout 자동 재시도, N회 실패 시 사용자 에스컬레이션
|
||||
6. **QA 체크리스트 강제** — 스프린트 타입별 템플릿, 다랑이가 체크박스 다 채워야 pass
|
||||
|
||||
## 아키텍처 개요
|
||||
|
||||
```
|
||||
사용자 (디스코드)
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────────┐
|
||||
│ hanarang-rails orchestrator │
|
||||
│ (XState FSM + SQLite + validator) │
|
||||
└──────────────────┬─────────────────┘
|
||||
│
|
||||
┌───────────┼───────────┬───────────┐
|
||||
▼ ▼ ▼ ▼
|
||||
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
|
||||
│ 하랑 │ │ 나랑 │ │ 다랑 │ │ 이랑 │
|
||||
│Planner│ │ Impl │ │ QA │ │Deploy│
|
||||
└──────┘ └──────┘ └──────┘ └──────┘
|
||||
│ │ │ │
|
||||
└───────────┴─ OpenClaw spawn ──────┘
|
||||
│
|
||||
▼
|
||||
┌────────────┐
|
||||
│ Discord 알림│ ← 사용자 알림 전용
|
||||
└────────────┘
|
||||
```
|
||||
|
||||
## 기술 스택
|
||||
|
||||
| 레이어 | 선택 |
|
||||
|---|---|
|
||||
| 런타임 | Node 22 + TypeScript (strict) |
|
||||
| 상태 머신 | XState v5 |
|
||||
| 스키마 | Zod |
|
||||
| 영속화 | SQLite (better-sqlite3) |
|
||||
| 프로세스 | execa + AbortController |
|
||||
| CLI | citty |
|
||||
| 로그 | pino |
|
||||
| 디스코드 | discord.js v14 |
|
||||
| 테스트 | Vitest |
|
||||
|
||||
## 상태
|
||||
|
||||
🚧 **기획 단계** — `.plans/` 디렉토리 참조.
|
||||
|
||||
자세한 내용:
|
||||
- [`.plans/OVERVIEW.md`](.plans/OVERVIEW.md) — 프로젝트 전체 개요
|
||||
- [`.plans/failure-audit.md`](.plans/failure-audit.md) — 실패 감사
|
||||
- [`.plans/design/`](.plans/design/) — 설계 문서
|
||||
- [`.plans/sprints/`](.plans/sprints/) — 스프린트 상세
|
||||
|
||||
## 라이선스
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user