CrystaCode 프로젝트 내 단일 소스 아키텍처를 통한 AI 에이전트 준수 강제화

AI 에이전트가 논리적 이탈 없이 프로젝트 규칙을 실행하려면 엄격한 디렉토리 구조가 필요합니다. 규칙의 중복은 실행 실패를 초래합니다. 단일 진실 공급원 (Single source of truth)을 구축하십시오. 각 규칙을 정확히 한 곳에서만 정의하십시오. 보조 파일은 오직 라우팅 파라미터 (Routing parameters)로만 기능해야 합니다.

시스템 아키텍처 (System Architecture)

AGENTS.md                        # 기본 엔트리 파일 (Primary entry file)
CLAUDE.md                        # AGENTS.md를 가리키는 포인터 (Pointer)

...

구성 요소 사양 (Component Specifications)

기본 노드 (Primary Node)

AGENTS.md: 필수 초기화 파일입니다. 라우팅 매트릭스 (Routing matrices)를 포함합니다. 파일 확장자 트리거를 개설하고 이를 특정 필수 문서에 매핑합니다.

리디렉션 노드 (Redirection Nodes)

CLAUDE.md: 파서 (Parser)가 AGENTS.md를 평가하도록 지시하는 단일 포인터를 포함합니다.
.github/instructions/: GitHub Copilot을 모듈별 규칙으로 리디렉션하는 포인터입니다.

운영 지침 (Operational Directives)

agents/rules/: 특정 프로젝트 모듈에 매핑된 격리된 절차적 단계 및 체크리스트입니다. 규칙 정의를 skills 디렉토리로 위임합니다.
agents/skills/: 작업에 대한 정확한 전제 조건을 규정하는 문맥적 트리거 (Contextual triggers)입니다. 절대적인 규칙 텍스트는 docs/ 저장소로 위임합니다.

절대적 문서 (Absolute Documentation)

docs/: 확정적인 저장소입니다. 완전한 기술 사양과 규칙 텍스트를 포함합니다. 규칙 정의를 위한 유일한 장소입니다.

자동 미러 (Automated Mirrors)

.claude/skills/: agents/skills의 자동 미러입니다. 수동 수정은 엄격히 금지됩니다.

인터셉터 스크립트 프로토콜 (Interceptor Script Protocol)

styling-guard.ps1 훅 (Hook)은 세션 마커를 기반으로 실행을 제어하여 준수 사항을 강제합니다.

1. 요청 가로채기 (Intercept Request):
   스크립트는 실행 전 AI의 파일 수정 요청을 가로챕니다 (Intercept).

2. 대상 파라미터 평가 (Evaluate Target Parameters):
   파일 확장자를 대상 파라미터 (.scss, .razor)와 대조하여 평가합니다. 일치하지 않는 파일은 가로채기를 건너뜁니다.

3. 제품 연관성 확인 (Ascertain Product Association):
   스크립트는 대상 파일 경로를 평가하여 연관된 프로젝트 모듈을 식별합니다.

4. 세션 데이터 조회 (Query Session Data):
   스크립트는 파일 유형 및 모듈에 해당하는 기존 실행 마커 (Execution Marker)가 있는지 세션 데이터를 확인합니다. 마커가 존재하면 AI는 가로채기를 우회합니다.

5. 실행 중단 (Halt Execution):
   마커가 없는 경우 실행이 차단됩니다. AI는 필요한 기술 문서 (Skill Documentation)를 파싱하도록 하는 명시적인 지침을 받습니다.

6. 실행 마커 기록 (Write Execution Marker):
   스크립트는 세션 데이터에 실행 마커를 기록합니다. 동일 세션 내의 후속 수정 시도는 중단 없이 진행됩니다.

인터셉터 구현 로직 (Interceptor Implementation Logic)
가로채기 메커니즘은 세션 마커가 없을 때 실행을 중단하기 위해 명시적인 표준 에러 (Standard Error) 지침을 출력합니다:

배포 체크리스트 (Deployment Checklist)

if ($category -eq 'scss') {
    [Console]::Error.WriteLine(
        "MANDATORY styling gate: this is the first .scss edit in this session for the " +
...

• 루트 엔트리 노드 (AGENTS.md) 초기화.
• 파일 확장자를 필수 규칙에 매핑하는 라우팅 매트릭스 (Routing Matrix) 정의.
• 모듈별 규칙을 별도의 파일로 격리.
• 단일 진실 공급원 (Single Source of Truth)으로서 확정적인 규칙 저장소 (docs/) 구축.
• 명시적인 운영 전제 조건이 포함된 기술 트리거 (Skill Triggers) 정의.
• 실행을 중단하고 규칙 검토를 강제하는 인터셉터 스크립트 배포.
• 도구별 디렉토리 (.claude, .github)를 포인터 아티팩트 (Pointer Artifacts)로 제한.

즐겁게 이용하세요: CrystaCode