BlackAgents 앱 패턴
적용 시기
app/**, app/api/**, 또는 lib/**를 건드리는 기능이나 수정을 구현할 때 이 문서를 읽으세요. 엄격한 제약 조건은 typescript-strict 및 api-response-format 규칙에 있으며, 이 파일은 계층과 레시피를 설명합니다.
아키텍처 (계층 존중)
UI (components/features/, client) ──fetch──▶ API routes (app/api/**/route.ts)
│ { success, data | error }
Domain (lib/artifacts/, lib/standards/)
│ parse / serialize / graph
Filesystem (lib/fs-service.ts)
│ resolveInWorkspace (no escape)
Workspace folder (.cursor / .claude ...)
규칙:
- 순수하고 플랫폼에 독립적인 로직은
lib/artifacts/**에 있습니다. React나next/server를 가져오지 않습니다. - HTTP 관련 사항은
app/api/**/route.ts에만 있습니다. - 모든 디스크 접근은
lib/fs-service.ts를 통해 이루어집니다. 라우트에서 직접node:fs를 호출하지 마십시오.
App Router 규칙
- 페이지는 기본적으로 서버 컴포넌트입니다. 상호작용/상태/이펙트가 필요한 경우에만
"use client"를 추가하세요. - 라우트 그룹:
/agents,/commands,/rules,/skills각각에는 목록 페이지,[name]편집 페이지,new페이지가 있습니다./new는 안내 마법사입니다. 기타 라우트:/graph,/standards,/export,/sync,/chat,/providers,/settings. - 클라이언트 기능 컴포넌트는
apiFetch(lib/api.ts)를 통해 데이터를 가져오고WorkspaceProvider에서 활성 작업 공간 상태를 읽습니다. 클라이언트에서 원시fetch나 직접적인 설정 읽기를 사용하지 마십시오.
API 라우트 레시피
import { ok, fail, handle } from "@/lib/api-response"
import { artifactInputSchema } from "@/lib/artifacts/schemas"
export async function POST(req: Request) {
return handle(async () => {
const parsed = artifactInputSchema.safeParse(await req.json())
if (!parsed.success) return fail(parsed.error.issues[0].message, 400)
// ...lib/artifacts + lib/fs-service를 통한 도메인 작업...
return ok({ /* data */ })
})
}
- 항상
ok/fail을 통해 반환하세요.handle로 감싸서 예외 발생 시500봉투가 되도록 하세요. - 설정(
lib/config.ts)에서 작업 공간 루트를 읽은 다음resolveInWorkspace(root, relPath)를 사용하세요. - 비밀은 서버 측에서만
lib/secrets.ts로 읽으세요. 자격 증명 누락 시fail("...", 412).
도메인 모델
lib/artifacts/:
types.ts—Artifact,ArtifactType,Platform,ArtifactFrontmatter(도구에 독립적).layout.ts—PLATFORM_LAYOUTS+artifactRelPath()/artifactDeletePath(); 플랫폼의 폴더/확장자를 아는 유일한 곳입니다.ACTIVE_PLATFORMS = ["cursor", "claude"], 기본값cursor.parser.ts—scanWorkspace(root)및parseArtifact(gray-matter사용); 스킬은<name>/SKILL.md디렉토리로 재귀적으로 탐색됩니다.serializer.ts—serializeArtifact(input)는 프론트매터 + 본문을 작성합니다. 규칙은name을 생략합니다 (파일 이름으로 식별).schemas.ts—nameSchema(kebab-case),artifactInputSchema,normalizeExtra(유형별 프론트매터).graph.ts— 작성 규칙에서 교차 참조를 추출합니다.
교차 참조 규칙 (그래프가 읽는 대상)
| 출발 → 도착 | 본문 규칙 |
|---|---|
| 명령 → 에이전트 | agent-name (굵게) |
| 에이전트 → 규칙 | `rule-name` 규칙 |
| 에이전트 → 스킬 | `skill-name` 스킬 |
| 규칙 → 규칙 | 관련 규칙: a, b. |
| 규칙 → 스킬 | 참고: x 스킬. |
이 정확한 규칙으로 본문을 작성해야 관계 그래프와 어시스턴트의 링크 감지가 작동합니다.
파일 시스템 안전
export function resolveInWorkspace(root: string, relativePath: string): string {
// root 아래에서 relativePath를 확인하고 이스케이프 시 WorkspaceError 발생
}
모든 읽기/쓰기는 이 함수를 통해 작업 공간 상대 경로로부터 구성되어야 합니다. 절대 경로를 연결하거나 클라이언트가 제공한 절대 경로를 허용하지 마십시오.
작업 공간 외부 지속성
~/.black-agents/config.json— 저장된 작업 공간 + 활성currentPath(lib/config.ts).~/.black-agents/secrets.json— LLM 키, 모드0600, 서버 전용 (lib/secrets.ts).<workspace>/.black-agents/standards.md— 작업 공간별 작성 표준 재정의.BLACK_AGENTS_CONFIG_DIR로 설정 디렉토리를 재정의할 수 있습니다 (테스트에 유용).
사용 방법
참조 전용입니다. 페르소나와 워크플로는 feature-developer 에이전트에 있습니다. 안전장치는 typescript-strict 및 api-response-format 규칙에 있습니다. 이 파일을 사용하여 로직을 올바른 계층에 배치하고 라우트 레시피를 복사한 다음, UI는 uiux-designer 에이전트에, 테스트 범위는 tester 에이전트에 넘기세요.