airails.dev
Spec-Driven BCE (sbce.space)의 본거지 — 최신 Java 및 웹 애플리케이션 구축, 그리고 레거시 엔터프라이즈 시스템을 해당 스택으로 마이그레이션하기 위한 개발 컨벤션(SKILLS.md), AGENTS.md를 제공합니다.
설치 (Installation)
git 없이 저장소를 다운로드한 후, 설치 프로그램을 실행하세요:
curl -fsSL https://raw.githubusercontent.com/AdamBien/airails/main/downloadSkills | java --source 25 /dev/stdin
cd airails
./installSkills
또는 첫 번째 단계 대신 git으로 클론하세요:
git clone https://github.com/AdamBien/airails
cd airails
./installSkills
이 설치 프로그램은 모든 스킬을 찾아 지원되는 각 에이전트 디렉토리(~/.claude/skills, ~/.vibe/skills, ~/.kiro/skills, ~/.copilot/skills, ~/.agents/skills, ~/.config/goose/skills)로 복사할 때 프롬프트를 표시합니다.
JDK나 git 없이, 로링(rolling) 스킬 릴리스에서 에이전트용 사전 패키징된 zip을 다운로드하여 홈 디렉토리에 압축 해제하세요:
curl -fsSLO https://github.com/AdamBien/airails/releases/download/skills/airails-claude.zip
unzip -o airails-claude.zip -d ~
각 zip 파일에는 에이전트의 스킬 디렉토리가 엔트리 경로에 포함된 모든 스킬이 들어 있습니다: airails-claude.zip, airails-vibe.zip, airails-kiro.zip, airails-copilot.zip, airails-codex.zip, airails-goose.zip. 에이전트 중립적인 airails-skills.zip은 동일한 스킬을 일반적인 skills/ 접두사 아래에 담고 있으므로, 이를 임의의 에이전트 구성 디렉토리 또는 사용자 지정 위치에 압축 해제하세요:
curl -fsSLO https://github.com/AdamBien/airails/releases/download/skills/airails-skills.zip
unzip -o airails-skills.zip -d ~/.claude
스킬을 직접 설치하는 AI 에이전트는 AGENTS.md를 따라야 합니다 — installSkills는 대화형 터미널(interactive terminal)을 필요로 합니다.
설치된 스킬 관리:
.
./installSkills -l # 사용 가능한 및 설치된 스킬 목록 보기
./installSkills -d <name> # 이름으로 스킬 삭제하기
./installSkills -h # 도움말 표시
스킬 레이어 (Skill Layers)
스킬들은 여러 층(layer)으로 구성됩니다. 각 레이어는 하나의 결정 세트를 고정합니다. 상위 레이어들은 이 결정을 직접 내리는 대신 요청만 합니다. 하위 레이어는 조합된 스킬이 침묵하는 곳이라면 어디든 적용되며, 조합된 스킬은 이를 전문화할 뿐 절대 모순시키지 않습니다. 고정된 결정(fixed decision)이란 에이전트가 태스크별로 재발견하지 않는 것을 의미합니다.
- 언어적 (Linguistic) — 문구 및 테스트 형태. ears-tests: 6가지 EARS 패턴으로 구성되며, 각 패턴은 고정된 전제 조건(precondition)/트리거(trigger)/응답(response) 튜플에 매핑됩니다. 하나의 명세 ID는 하나의 테스트 행을 산출하며, 주어(subject)는 항상 BC입니다.
- 의미론적 (Semantic) — 범위 및 명명 규칙. sbce: 하나의 기능 사양(capability spec)은 하나의 BC와 하나의 패키지에 해당합니다. 경계 연산(boundary operations)은 동사-명사 형태이며 전송에 중립적입니다. 요구사항 ID는 안정적이며 절대 재번호 매김되지 않습니다.
- 아키텍처적 (Architectural) — 구조 및 어휘. bce와 concerns: 레이어 책임, 패키지 구조, 명명 금지 사항 등을 정의합니다.
- 기술적 (Technological) — 런타임, 배치(layout), 빌드, 검증 루프. 스택 스킬: java-cli-script, java-cli-app, microprofile-server, aws-cdk, web-static, web-sprinkles, web-components. 빌딩 블록: zb, zargs, zcfg, zcl, zjson. 레이어 1~3은 스택 스킬에게 코드가 어디에 위치하는지, 그리고 그것이 정상(green)인지 여부를 요청합니다.
- 관용적 (Idiomatic) — 구문 및 스타일. java-conventions, javascript-conventions, web-conventions: 스택 스킬이 침묵하는 곳이라면 어디든 기본값으로 적용됩니다.
- 판단 (Judgment) — 완료의 정의(definition of done).
system-tests는 중립 규칙(neutral rule)이며, web-system-tests, zunit, continuous-testing, 그리고 characterization-tests를 통해 구현됩니다. 이 스택 자체의 테스트 루프가 오라클(oracle)이며, 에이전트는 결합성(convergence)을 스스로 인증하지 않습니다.
순서 외부에 있는 것들:
- 독점 접지(Exclusive grounding) — 레이어 4와 5에 대한 선택 규칙: 표준 우선, 종속성 없음(zero dependencies), 빌드 단계 없음. 모델이 공개 표준에 대해 가지는 사전 지식(prior)은 web-conventions의 Baseline 스냅샷에 의해 통제됩니다.
- 통제된 압축 해제(Controlled decompression) — 수정자들(modifiers)이 각각 하나의 결정을 열어줍니다: showtime은 검증을 건너뛰고, web-latest는 Baseline 정책을 해제하며, web-pwa는 오프라인 지원을 추가하고, web-performance-reviewer, web-standards-reviewer, 그리고 bce-reviewer는 선택적 검토(opt-in reviews)를 추가합니다. 트랜스포머(Transformers)는 레이어 3–5에 기존 코드에 적용하며: java-distiller, python-to-java, simplifier; enterprisifier가 이를 역전합니다.
- 복구 및 투영(Recovery and projection) — capability-brief는 그린필드 의도(greenfield intent)를 유스 케이스 또는 사용자 스토리로 포착하여 레이어 2에 공급하고; 마이그레이션 스킬들은 레거시 코드에서 도메인 어휘(domain vocabulary)를 복구하여 마찬가지로 공급합니다: concept-extractor, concept-clarifier, bc-carver, concept-annotator가 담당하며, 이는 migration-advisor에 의해 라우팅됩니다. readme, bce-diagrams, mermaid, 그리고 drawio는 인간을 위해 레이어 2와 3을 렌더링합니다.
내부 구성 요소
Spec-Driven BCE (SBCE)
하나의 기능 명세(capability spec)는 하나의 비즈니스 컴포넌트가 되며, 이 명세가 경계 계약(boundary contract)입니다 (sbce.space). 기능을 선언한 다음, 해당 코드를 스택 자체의 테스트 루프를 통해 수렴시킵니다.
- sbce — 워크플로우:
new는 기능을 기능 명세로 분해하고, apply는 코드를 명세에 맞게 수렴시키며; bce와 스택 기술(java-cli-app, microprofile-server, web-components)과 결합합니다.
- ears-tests — 기능 명세의 EARS 요구사항 진술에서 생성된 매개변수화된 (테이블 기반) 테스트로, 요구사항 ID당 한 줄이 레이블링됩니다.
- capability-brief — 도메인 소유자(domain owner)와 함께 완성되는 사용 사례 또는 사용자 스토리로, 완전성 체크리스트를 사용하여
/sbce new가 질문 없이 명세를 한 번에 작성하게 합니다.
Java
-
java-conventions — 모든 Java 컨텍스트에서 모던한 구문, 네이밍, 가시성(visibility), 스트림(streams), 예외 처리를 아우르는 조합 가능한 Java 25 코드 컨벤션입니다.
-
concerns — 클래스나 패키지가 존재하는 이유를 기록하는 @Concern 마커 어노테이션: 관측 가능성 및 외부 시스템을 위한 시작 유형(starter kinds)과, 프로젝트별 유형 추가가 가치가 있을 때의 진입 규칙(admission rules)이 포함됩니다.
-
java-cli-script — PATH를 통해 시스템 전체에서 사용 가능한, 의존성 제로(zero-dependency), 단일 파일 실행 Java 스크립트입니다. 더 긴 스크립트는 멤버들을 Boundary/Control/Entity 인터페이스 네임스페이스로 그룹화합니다 (bce 결합).
-
java-distiller — 기존 코드를 관용적인(idiomatic) Java 25로 단순화하고, 현대화하며, 리팩토링합니다.
-
python-to-java — Python 스크립트를 의존성 제로의 Java 25 CLI 프로그램으로 변환합니다.
-
enterprisifier — 코드를 최대 패턴, 간접 참조(indirections), 추상화(abstractions)를 사용하여 의도적으로 과잉 설계(overengineers)하는 도구로, 코믹하거나 교육적인 목적을 위해 사용됩니다.
-
zb — Java 21 이상 프로젝트의 컴파일, 빌드 및 패키징을 위한 제로 디펜던시 빌더입니다.
-
zb-release-pipeline — zb 프로젝트를 빌드하고 JAR 파일을 GitHub Release로 게시하는 GitHub Actions 파이프라인
-
zargs — Java CLI 애플리케이션을 위한 제로 의존성, enum 기반 인자 구문 분석기(argument parsing)
-
zcfg — 속성 및 애플리케이션 설정을 로드하기 위한 제로 의존성 설정 유틸리티(Configuration Utility)
-
zcl — Java 애플리케이션에서 색상 터미널 출력을 위한 제로 의존성 컬러 로거(Colour Logger)
-
zhtmldb — 에이전트 데이터 저장소: 브라우징 가능하고 git-diff 가능한 XHTML 페이지 형태로 저장되는 키-값 레코드. zhtmldb CLI를 통해 구동됩니다.
-
zjson — org.json 소스를 프로젝트에 복사하여 사용하는 JSON 파싱 및 생성기. Maven/Gradle 의존성이 필요 없습니다.
-
zunit — java-cli-app 프로젝트를 위한 zunit 테스트를 생성하고 실행합니다.
-
zllm-scripts — 에이전트와 조합된 스킬(composing skills)이 OS 셸 명령 대신 실행하는, find, grep, cat 및 클립보드 명령어의 읽기 전용, root 제한 대체 명령어 세트와 JavaScript 임포트 인벤토리
Web
-
web-conventions — 모든 웹 프론트엔드를 위한 조합 가능한 기반: 시맨틱 HTML, 접근성(accessibility), 디자인 토큰(design tokens), 그리고 기본 브라우저 지원 정책(Baseline browser-support policy)
-
javascript-conventions — 조합 가능한 JavaScript 기반: ES 모듈(ES modules), 문법(syntax), 컬렉션(collections), 비동기성(asynchrony), 오류 처리(errors), JSDoc 타입(JSDoc types), 그리고 가장 최신 사용 가능한 ECMAScript를 선택하는 기능별(per-feature) 기본 검색(Baseline lookup)
-
web-static — 외부 종속성이나 빌드 시스템 없이 시맨틱 HTML과 CSS를 사용하는 현대적인 정적 웹사이트; web-conventions를 조합함
-
web-sprinkles — 작고 자족적인 ES 모듈로 향상된 정적 사이트: 향상 계약(enhancement contract), CSS 대 스크립트의 경계선(CSS-versus-script cut line), 그리고 스크립트를 제거한 검증 통과(verification pass with the scripts removed); web-static과 javascript-conventions를 조합함
-
web-components — 웹 컴포넌트, BCE 계층화(layering), lit-html, Redux Toolkit, 그리고 클라이언트 측 라우팅을 사용하는 단일 페이지 애플리케이션(Single-page applications); web-conventions를 조합함
-
web-system-tests — 실행 중인 프론트엔드를 대상으로 Playwright를 사용한 브라우저 구동 시스템 테스트: tests/ 레이아웃, baseURL과 webServer, 접근성 트리 로케이터(accessibility-tree locators), 크로스 엔진 실행(cross-engine runs), 선택적 커버리지(opt-in coverage); 시스템 테스트의 웹 구현체
-
web-latest — 기본 브라우저 지원 정책을 확장하는 실험 및 PoC(Proof of Concept)용 수정자: 폴백 없이 최신 웹 플랫폼 기능들을, 선언된 지원 하한선과 함께 제공; web-static, web-sprinkles 또는 web-components 위에 조합함
-
web-performance-reviewer — Chrome DevTools MCP를 통한 선택적 성능 검토: 스로틀링 트레이스(throttled traces), Core Web Vitals 임계값, 네트워크 폭포수(network waterfall), SPA용 힙 스냅샷 메모리 누수 확인(heap-snapshot leak checks); 검증 루프의 일부가 아님; web-static, web-sprinkles 또는 web-components 위에 조합함
-
web-standards-reviewer — 감지된 스택 기술의 웹 표준 및 필수 의존성 규칙에 따라 기존 웹 프로젝트를 간결하게 검토합니다: 빌드 단계, 비필수 의존성, 수작업 코드를 대체하는 플랫폼 API; 발견 사항당 한 줄; 검토만
-
web-pwa — 버전이 지정된 Cache API 프리캐시를 가진 수동 작성 서비스 워커를 통해 오프라인 지원을 추가하고, 웹 앱 매니페스트를 통한 설치 가능성을 제공하는 수정자입니다. 빌드 단계 없음, 생성 코드 없음; web-static, web-sprinkles 또는 web-components 위에 합성됩니다.
BCE