A-ISL 컴파일 (에이전트 내 컴파일러)
ISL(기본 스택 react-js → bin-react-js)에서 bin-<stackId>/를 생성합니다. Builder / queue / packet / lock / preflight CLI가 허용됩니다. 유료 isl-generator / Gemini / OpenAI는 금지됩니다.
이 스킬을 로드하는 모든 코딩 에이전트(Cursor, Claude Code, GitHub Copilot 등)와 함께 작동합니다. 저장소 루트에서 동일한 npm 런타임을 사용합니다.
사용자 요청 게이트 (불가침)
La modifica alla bin viene fatta solo tramite compile e solo ovviamente su richiesta dell'utente. (bin 수정은 컴파일을 통해서만, 그리고 사용자의 명시적 요청이 있을 때만 이루어집니다.)
- 사람이 명시적으로 컴파일을 요청한 경우에만(예: "compila", "/a-isl-compile", "build bin", "regenerate implementation", "run compile for ...") 이 스킬을 실행하고
bin-*아래에 씁니다. - 명시적인 컴파일 요청 없이 사양 전용 메시지, 자연어 기능 아이디어 또는 UX 수정 사항은 구현 작성을 트리거해서는 안 됩니다. 이러한 경우 a-isl-spec-author(또는 Spec 단계)로 보내고 중단합니다.
- "데모가 망가질 것" 또는 "루프를 완료하기 위해" Spec 편집 후 자동으로 컴파일하지 마십시오.
- 구현 폴더는 이 Compile 워크플로우(패킷 → 쓰기 → 잠금)를 통해서만 업데이트됩니다. 사람이 명시적으로 일회성 예외를 요청하지 않는 한
bin-*아래의 임시 패치를 A-ISL 경로로 취급하지 마십시오. - 사람이 컴파일을 요청하지 않은 경우:
bin-*편집을 거부하고 명시적인 컴파일 요청이 필요하다고 말해야 합니다.
사용 시기
- 사람이 Spec 단계를 완료하고 요청하여 빌드/컴파일/재생성하는 경우
- 사람이 Compile을 요청했기 때문에 업데이트된
*.isl.md에 맞게 프로젝트의bin-<stack>/을 정렬하는 경우
엄격한 제약 조건
- 유료 생성기 또는 API 코드젠 클라이언트를 실행하지 마십시오.
- 패킷의
targetPath에서 스택 bin 디렉토리에 각 구현 파일을 직접 작성합니다(전체 코드, TODO 스텁 없음). gen-lock.json만 업데이트하는 것은 컴파일이 아닙니다 —bin-<stack>/아래에 실제 쓰기가 이루어진 후에만 잠급니다.- ISL이 모호하거나 모순되는 경우: 중단하고 사용자에게 a-isl-spec-author로 돌아가라고 알립니다. 요구 사항을 임의로 만들지 마십시오.
- 사용자가 명시적으로 요청하지 않는 한 Compile 중에
vendor/isl-spec/를 열지 마십시오(Spec Agent 전용). - 기본적으로
queue --next+ 가벼운 패킷을 통해 한 번에 한 단위를 선호합니다. 전체 큐 JSON 또는 전체.build.md를 로드하지 마십시오.
출력 디렉토리
기본값: 사양 옆에 bin-<stackId> (예: --stack react-js → bin-react-js). 필요한 경우 --bin으로 재정의합니다. 동일한 작업 공간에 bin-react-js와 bin-csharp를 나란히 보관할 수 있습니다.
저토큰 워크플로우 (기본값)
preflight → builder (한 번) → 루프: queue --next → packet → [테스트 후] impl 작성 → (배치) lock
→ (선택 사항) npm run verify
0. Preflight (한 번)
npm run preflight -- --root examples/connect-four-workspace
구조/그래프/린트 게이트 전용 — 구현 정확성을 증명하지 않습니다. 실패하면 Compile 전에 Spec/린트를 수정하십시오.
1. Builder (배치당 한 번)
npm run builder -- examples/connect-four-workspace
토폴로지 순서는 build/build-manifest.json(스크립트 소유)에 있습니다. 컴파일 순서를 임의로 만들지 마십시오.
2. 다음 단위만
npm run queue -- --root examples/connect-four-workspace --next
루프의 모든 queue/packet 호출에 --stack <id> 를 전달합니다(기본값 react-js → bin-react-js/):
npm run queue -- --root <project> --next --stack blazor
npm run packet -- --root <project> --next --stack blazor
ID: react-js, blazor, winforms, csharp (라이브러리 전용), python, python-fastapi. 선택적 --bin <path>는 출력 폴더를 재정의합니다.
대상 재컴파일 — 사람이 하나 또는 몇 개의 단위를 재생성하도록 요청할 때(잠금이 그렇지 않으면 건너뛸 수 있음):
npm run queue -- --root <project> --next --only dungeon --stack react-js
npm run packet -- --root <project> --next --only dungeon --stack react-js
# 또는 이름으로 패킷:
npm run packet -- --root <project> --only dungeon --stack react-js
--only는 반복될 수 있습니다. 토큰: 단위 기본 이름(dungeon), dungeon.isl.md 또는 ./dungeon. 큐 JSON의 이유: force-only. 요청된 하위 집합만 있을 때 작업 공간 전체 --force를 사용하지 마십시오.
next.buildFile / next.targetPath를 사용하십시오. next가 null이면 중단합니다(큐 비어 있음).
사람이 개요를 요청한 경우에만 전체 --json 큐를 사용하십시오.
3. 가벼운 패킷 (기본 컨텍스트)
npm run packet -- --root examples/connect-four-workspace --build-file "<abs.build.md>"
# 또는
npm run packet -- --root examples/connect-four-workspace --next
패킷에는 다음이 포함됩니다: 이 단위의 SOURCE 마크다운, 대상 경로, 스택 제약 조건 하위 집합, 동일한 bin-<stack>/에 있는 종속성 파일의 경로.
인라인 .ref.md 블롭은 제외됩니다.
패킷에서 파일을 작성합니다(아래 EXT-001 순서 참조). 나열된 경로에서 실제 종속성 모듈을 가져옵니다.
3a. 종속성 선언 조회 (EXT-002)
이 단위를 작성하기 전에 종속성 심볼(메서드/함수/타입)의 정확한 선언이 필요한 경우:
npm run lookup-decl -- --stack <id> --name <SpecOrCallName> --file <abs-or-rel-bin-path> [--workspace <project>]
# 또는 bin 폴더 스캔(생성된 *.test.* / *.Tests.cs는 --include-tests가 없는 한 건너뜀):
npm run lookup-decl -- --stack <id> --name <Name> --dir <bin-<stack>> --workspace <project>
- 종료 0 = 일치, 2 =
no_match, 3 = 사용법/경로/스택 오류. - stdout JSON 읽기:
candidates[selected]사용 (signatureText,leadingContext,enclosingType, 후보별kind). 서명을 찾기 위해 정규식을 만들거나 전체 종속성 파일을 열지 마십시오. - 패턴과
callSymbol은 스택 구성(declaration-patterns.ts/stacks.config.ts)에 있습니다. 스킬은 이 CLI만 호출해야 합니다. - 경로는
--workspace와bin-*세그먼트 아래에서 확인되어야 합니다(심볼릭 링크 이스케이프 → 종료 3).
3b. EXT-001 생성된 테스트 (Spec이 선택한 경우)
검증 가능 시나리오 = `id: …`와 - Call: …를 모두 가진 테스트 시나리오(docs/isl-agent-profile.md 참조). Spec Author가 결정하며, 모든 역할이 선택할 수 있습니다.
단위당, 동일한 턴:
- SOURCE에 ≥1개의 적격 시나리오가 있는 경우: 먼저 생성된 테스트 파일을 덮어씁니다(경로 = impl 기본 이름 + 동일한
bin-<stack>/아래의stack.verify.testSuffix, 예:domain-sheet.test.js/domain-sheet.Tests.cs). Spec 시나리오 + 서명에서만 어설션합니다.Call을stack.verify.callSymbol(stacks.config.ts에서as-is|pascal-case|snake-case)을 통해 심볼에 매핑합니다. react-js Domain/Logic: 각 Call은 명명된 내보내기여야 합니다. 테스트는import { <Call> } from "./<file>"을 해야 합니다.import Unit from …; Unit().<Call>()은 절대 안 됩니다. 작업 공간에bench/call-map.json이 있으면"<unit>.<Call>"에서export를 확인하고 해당 이름을 가져옵니다(고정 점수와 동일한 계약). 산문 전용 시나리오에 대해 테스트 케이스를 만들지 마십시오. 테스트 파일이 작성되기 전에 impl 파일을 열거나 편집하지 마십시오. - 그런 다음
targetPath에 impl을 작성하여 해당 테스트와 Contract를 충족시킵니다. react-js Domain/Logic: 모든 Capability에 대해export function <Call>/export const <Call>을 사용합니다. Capability를 래핑하는 기본 내보내기 팩토리는 금지됩니다. - 적격 시나리오가 0개인 경우: impl만 작성하고, 해당 단위에 대해 이전에 생성된 테스트 파일이 여전히 존재하면 삭제합니다. Domain/Logic에 대해 여전히 명명된 capability 내보내기를 사용합니다.
- verify 실패 시:
--only로 impl만 재컴파일할 수 있습니다(테스트 파일 유지). 테스트를 통과시키기 위해 테스트를 다시 작성해서는 안 됩니다(명명된 가져오기를 기본 팩토리로 변경하는 것 포함). 시나리오/Call/예상 결과가 잘못된 것 같으면 → 중단하고 사람을 a-isl-spec-author로 보냅니다. - Domain/Logic(또는 기타 적격) 배치 후
npm run verify -- --root <project> --stack <id>를 제안할 수 있습니다. 잠금을 위해 통과가 필요하지는 않습니다. 잠금은 빌드 해시 캐시로 유지됩니다.
Spec 변경 후 전체 단위 재컴파일: 현재 Spec에서 전체 테스트 파일을 재생성한 다음 impl을 생성합니다(이전 테스트와 병합하지 않음).
4. 잠금 (가능하면 배치)
1–5회의 성공적인 쓰기 후:
npm run lock -- --root examples/connect-four-workspace --build-file "<abs1>" --build-file "<abs2>"
5. 복잡성에 따른 에이전트 배칭 (컨텍스트 위생)
많은 단위를 컴파일하는 긴 단일 에이전트 세션은 나중 단위나 큰 패킷을 과소 구현하는 경향이 있습니다(이전 빈으로 컨텍스트가 채워짐). 다음을 선호하십시오:
| 단위 종류 | 컴파일 방법 |
|---|---|
| 리프 / 소형 | 동일한 에이전트, 여러 queue --next → 쓰기 → 잠금 배치 |
| 대형 / 허브 | 새 에이전트 / 새 채팅: --only <unit> → 패킷 → SOURCE의 모든 capability 구현 → 잠금 |
| 수리 (검토/플레이테스트 후) | 새 에이전트 + 실패한 단위에만 --only |
다음 중 하나라도 해당되면 단위를 대형으로 취급합니다(스택 비종속적):
- 긴 SOURCE / 하나의
.isl.md에 많은####capability - 높은 팬인: 다른 많은 단위가 이를 참조하거나, 많은 종속성을 참조함
- 그래프의 많은 부분을 조정하는 프레젠테이션 또는 Logic(셸/퍼사드/세션 경계)
- 해당 단위의 패킷 또는 이전 컴파일에 생략된 Flows 이력이 있음
기본적으로 리프당 하나의 에이전트를 생성하지 마십시오(비용). 허브에서 새로 고치지 않고 하나의 에이전트에서 전체 대형 작업 공간을 실행하지 마십시오.
대형 단위 프롬프트: 저장소 루트, --stack, --only <unit>, "SOURCE의 모든 capability 구현, 생략된 Flows 없음." agent-skills/a-isl-compile/SKILL.md(또는 .cursor/skills, .claude/skills, 혹은 .github/skills 아래의 호스트 복사본)를 따릅니다.
에스컬레이션 테이블 (가벼운 액세스로 충분하지 않을 때)
| 상황 | 조치 |
|---|---|
| 패킷 정상, 종속성 빈 존재, ISL 명확 | 가벼운 액세스만 → 파일 쓰기 |
패킷 종료 / missingDependencyBins | 중단 — 큐/순서 수정; API를 임의로 만들지 마십시오 |
| 종속성의 정확한 선언/서명 필요 | npm run lookup-decl (EXT-002); JSON selected 사용 — API를 임의로 만들지 마십시오 |
lookup-decl 종료 2 (no_match) | Spec Call/이름 + 종속성 경로 재확인; 서명을 임의로 만들지 마십시오 |
| 패킷 불완전 / SOURCE 마커 없음 | 이 단위의 fullBuildFile을 한 번 읽습니다 |
| 모호하거나 모순된 ISL | 중단 → Spec Agent; vendor 탐색 금지 |
| 사람이 전체 재빌드 감사 요청 | --force / 전체 큐 --json 허용 |
단위별 쓰기 규칙
모든 생성된 파일의 헤더:
/**
* DO NOT EDIT THIS FILE DIRECTLY
* ----------------------------------
* 이 파일은 ISL 컴파일러에 의해 생성되었습니다.
* 출처: <basename-of-.isl.md>
* 대신 ISL 파일을 편집하십시오.
*/
스택 규칙을 따릅니다(기본값 react-js). 전체 구현 — TODO 스텁 없음.
경로
| 도구 | 진입점 |
|---|---|
| Preflight | npm run preflight -- --root <project> |
| Builder | npm run builder -- <project> |
| Queue next | npm run queue -- --root <project> --next |
| Packet | npm run packet -- --root <project> --next |
| Lock | npm run lock -- --root <project> --build-file <abs>… |
| Verify | npm run verify -- --root <project> [--stack <id>] [--only <unit>] |
| Lookup decl | `npm run lookup-decl -- --stack --name --file |
| Lint | npm run lint -- <file.isl.md> |