Skip to main content
Glama

당신은 AI 엔지니어를 고용했습니다. 아주 뛰어납니다. 그런데 오늘 같은 VS Code 확장 프로그램을 두 번 설치했고, 절대 정리하지 않을 Docker 컨테이너 6개를 띄웠으며, 디스크 여유 공간이 12 GB에서 한 세션 만에 0 KB가 되었습니다.

디스크가 가득 차면 우아하게 실패하지 않습니다. VS Code, 터미널, Docker, 데이터베이스가 동시에 죽습니다.

ForgeCraft는 AI 코딩 어시스턴트가 그 안에서 작동하는 품질 계약입니다 — 빠르게 빌드하면서도 집을 태우지 않도록 해줍니다.

npx forgecraft-mcp setup .

지원 도구: Claude (CLAUDE.md) · Cursor (.cursor/rules/) · GitHub Copilot (.github/copilot-instructions.md) · Windsurf (.windsurfrules) · Cline (.clinerules) · Aider (CONVENTIONS.md)


AI 지원 소프트웨어 개발을 위한 품질 프레임워크

모든 세션, 모든 프로젝트, 모든 AI 어시스턴트 — 동일한 7가지 속성 생성 사양(Generative Specification) 모델로 측정됩니다. 감이 아닙니다. 린터 점수가 아닙니다. 14점 만점의 점수로 격차가 정확히 어디에 있고 왜 그런지 알려줍니다.

$ npx forgecraft-mcp verify .

| Property        | Score | Evidence                                        |
|-----------------|-------|-------------------------------------------------|
| Self-Describing | ✅ 2/2 | CLAUDE.md — 352 non-empty lines                |
| Bounded         | ✅ 2/2 | No direct DB calls in route files              |
| Verifiable      | ✅ 2/2 | 64 test files — 87% coverage                   |
| Defended        | ✅ 2/2 | Pre-commit hook + lint config present           |
| Auditable       | ✅ 2/2 | 11 ADRs in docs/adrs/ + Status.md              |
| Composable      | ✅ 2/2 | Service layer + repository layer detected       |
| Executable      | ✅ 2/2 | Tests passed + CI pipeline configured           |

Total: 14/14 ✅ PASS · Threshold 11/14

속성

검사 내용

자기 설명적(Self-Describing)

코드베이스가 당신 없이 스스로를 설명하는가?

경계적(Bounded)

비즈니스 로직이 라우트로 새어 나오고 있지 않은가?

검증 가능(Verifiable)

테스트가 있고, 실제 런타임에서 통과했는가?

방어적(Defended)

훅이 나쁜 커밋이 들어오기 전에 차단하는가?

감사 가능(Auditable)

모든 아키텍처 결정이 기록되고 찾을 수 있는가?

조립 가능(Composable)

도메인을 건드리지 않고 데이터베이스를 교체할 수 있는가?

실행 가능(Executable)

이 코드가 실제로 실행되었다는 CI 증거가 있는가?


Related MCP server: MCP Policy Gatekeeper

개발 환경 위생 — 규약으로 강제

ForgeCraft는 모든 프로젝트의 AI 지침에 강제 가능한 규칙을 주입하여 환경 오염을 사고가 아닌 규약 위반으로 만듭니다.

VS Code 확장 프로그램 설치 전: code --list-extensions | grep -i <name>. 필수 메이저 버전 범위의 버전이 이미 있으면 설치하지 않습니다. 같은 확장 프로그램을 하루에 두 번 다운로드하지 않습니다.

Docker 컨테이너 생성 전 확인: docker ps -a --filter name=<service>. 이미 있으면 생성하지 말고 시작합니다. docker run(항상 새로 생성)보다 docker compose up(재사용)을 선호합니다. 로그는 500 MB로 제한됩니다. docker system prune -f는 비상 조치가 아니라 정기 유지보수 단계로 문서화됩니다.

예외: 플러그인 세트나 메이저 버전이 의미 있게 다른 경우 동일 서비스의 여러 컨테이너가 허용됩니다 — 예를 들어 표준 postgres 컨테이너 옆에 postgres-pgvector 컨테이너. 변형을 반영하여 컨테이너 이름을 지정하세요(예: db-pgvector, db-timescale). 그렇지 않으면 중복 제거 규칙이 적용됩니다.

Python 가상 환경 프로젝트 루트당 .venv 하나. Python major.minor 버전이 일치하면 재사용합니다. 독립 설치 가능한 패키지가 아닌 한 하위 디렉터리에 venv를 만들지 않습니다. pip list --not-required로 사용되지 않는 의존성을 식별합니다.

합성 및 시계열 데이터 생성된 데이터를 100 MB 이상 쓰기 전에 AI는 묻습니다: 원본 유지, 통계적으로 압축, 아니면 실행 후 삭제? 코드 참조가 없는 7일 이상 된 합성 데이터셋: 삭제를 요청합니다.

일반 알려진 빌드 산출물(node_modules/, .venv/, dist/) 외부에서 작업 공간이 2 GB를 초과하면 경고를 표시하고 중지합니다. 작업 공간을 조용히 키우지 않습니다.


프로젝트 설정 — 한 문장으로

Read the spec in docs/specs/, set up this project with ForgeCraft,
scaffold it with the right tags, recommend the tech stack, start building.

이것이 온보딩 프롬프트의 전부입니다. ForgeCraft가 사양을 읽고, AI가 태그를 할당하고, ForgeCraft가 지침 파일을 작성하고 Status.md, docs/adrs/, docs/PRD.md, docs/TechSpec.md, 훅, 스킬을 생성합니다. AI는 전체 컨텍스트를 갖습니다. 당신은 빌드를 시작합니다.

ForgeCraft는 프로젝트를 스캔하고, 스택을 자동 감지하며, 116개의 선별된 블록 — SOLID, 헥사고날 아키텍처, 테스팅 피라미드, CI/CD, 24개 도메인별 규칙 세트 — 에서 맞춤형 지침 파일을 몇 초 만에 생성합니다.


품질 게이트

품질 게이트는 AI 어시스턴트가 정의된 시점 — 커밋 전, 릴리스 전, 배포 후 — 에 실행하는 구조화된 통과/실패 검사입니다. 린터 규칙이 아닙니다. 각 게이트에는 조건, 증거 요구 사항, 인간 검토 필수 여부 플래그가 있습니다.

게이트는 릴리스 단계별로 구성되어 그린필드 프로젝트 첫날에 릴리스 전 혼돈 테스트를 실행하지 않도록 합니다:

단계

예시 게이트

개발(development)

단위 테스트 통과 · 린트 클린 · 레이어 위반 없음 · 하드코딩된 시크릿 없음

릴리스 전 강화(pre-release hardening)

변형 테스트 ≥80% · DAST 스캔 · 2× 피크 부하 · 혼돈(Toxiproxy)

릴리스 후보(release candidate)

OWASP Top 10 침투 테스트 · 전체 변형 감사 · 호환성 매트릭스 · 접근성

배포(deployment)

카나리 구성 검증 · 스모크 테스트 통과 · 관측 가능성 확인

배포 후(post-deployment)

합성 프로브 활성 · 30분 오류 창 모니터링 · 장애 대응 런북 검토

requires_human_review: true로 태그된 게이트는 자동 통과할 수 없습니다 — 일부 검사는 인간이 필요합니다.

전체 게이트 라이브러리, 기여 가이드, 스키마는 품질 게이트 저장소 →에 있습니다.


ADR, 자동 시퀀싱

모든 비자명한 아키텍처 결정은 기록됩니다. ForgeCraft는 MADR 형식으로 docs/adrs/NNNN-slug.md를 자동 시퀀싱합니다 — 컨텍스트, 결정, 대안, 결과. AI 어시스턴트는 과거의 선택을 추론합니다. 팀은 더 이상 그 결정을 재론하지 않습니다.

npx forgecraft-mcp generate_adr . --title "Use event sourcing for order history" \
  --status Accepted \
  --context "Order mutations need full audit trail for compliance" \
  --decision "Append-only event log, project current state on read"
# → docs/adrs/0004-use-event-sourcing-for-order-history.md

AI 어시스턴트 기본 설정 vs ForgeCraft

claude init, Cursor의 워크스페이스 규칙, Copilot의 지침 파일로 시작할 수 있습니다. ForgeCraft는 프로덕션 표준에 도달하게 해줍니다 — 모든 AI 어시스턴트, 모든 세션, 팀의 모든 엔지니어에게.

기본 AI 설정

ForgeCraft

지침 파일

일반적, 만능형

스택에 맞춘 116개 선별 블록

AI 어시스턴트

도구마다 다름

Claude, Cursor, Copilot, Windsurf, Cline, Aider

아키텍처

없음

SOLID, 헥사고날, 클린 코드, DDD

테스팅

기본 언급

테스팅 피라미드, 커버리지 목표, 변형 게이트

도메인 규칙

없음

24개 도메인 (핀테크, 헬스케어, 게이밍…)

품질 점수

없음

14점 만점 GS 점수 — 격차가 어디인지 정확히 알 수 있음

릴리스 단계

없음

개발부터 배포 후까지 7단계

개발 위생

없음

VS Code, Docker, Python venv, 디스크 가드

ADR

없음

자동 시퀀싱, MADR 형식

세션 연속성

없음

Status.md + forgecraft.yaml로 컨텍스트 유지

드리프트 감지

없음

refresh가 범위 변경 감지

워크플로 플레이북

설정 후, AI는 컨텍스트를 갖습니다. 이 프롬프트가 작업을 지시합니다. 복사, 붙여넣기, 실행.

상황

프롬프트

새 프로젝트 — 구조 스캐폴딩

그린필드 설정

기존 프로젝트 — ForgeCraft 통합

브라운필드 통합

감사에서 file_length 실패 표시

책임별로 분해

감사에서 hardcoded_url 실패 표시

환경 변수로 추출

감사에서 hardcoded_credential 실패 표시

시크릿 제거 — 이걸 먼저 하세요

감사에서 layer_violation 실패 표시

라우트 → DB 직접 호출 수정

감사에서 mock_in_source 실패 표시

프로덕션에서 목 옮기기

감사에서 missing_prd 실패 표시

사양 문서 역설계

감사에서 stale_status 실패 표시

Status.md 업데이트

점수 ≥ 80이고 출시 준비 중

릴리스 전 강화

방금 프로덕션에 배포함

배포 후 체크리스트

프로젝트 범위 변경됨

드리프트 감지

전체 워크플로 플레이북 · 온라인 버전


작동 방식

# First-time setup — auto-detects your stack
npx forgecraft-mcp setup .
flowchart TD
    A["<b>setup .</b><br/>npx forgecraft-mcp setup ."] --> B["Phase 1 — Analyze<br/>Reads spec · infers tags"]
    B --> C{AI assistant\nin the loop?}
    C -->|"Yes (MCP)"| D["Phase 2 — Calibrate<br/>LLM corrects tags from spec<br/>Writes forgecraft.yaml · CLAUDE.md<br/>PRD.md · hooks · ADR-000"]
    C -->|"No (CLI only)"| E["⚠️ CLI-only mode<br/>Directory heuristics only<br/>→ configure an AI assistant"]
    D --> F["<b>check_cascade</b><br/>5-step readiness gate<br/>1 · Functional spec<br/>2 · Architecture + C4<br/>3 · Constitution<br/>4 · ADRs<br/>5 · Use cases"]
    F --> G{All 5 passing?}
    G -->|"Stubs / missing"| H["Fill artifacts<br/>docs/PRD.md · docs/adrs/<br/>docs/use-cases.md"]
    H --> F
    G -->|"✅ All pass"| I["<b>generate_session_prompt</b><br/>Bound context for next task"]
    I --> J["Implement with TDD<br/>RED → GREEN → REFACTOR<br/>+ Documentation Cascade"]
    J --> K["<b>audit_project</b><br/>Score 0 – 100"]
    K --> L{Score ≥ 90?}
    L -->|"Violations found"| M["WORKFLOWS.md remediation<br/>file_length · layer_violation<br/>hardcoded_url · missing_prd"]
    M --> J
    L -->|"✅ Score ≥ 90"| N["<b>close_cycle</b><br/>Re-check cascade · assess gates<br/>promote to registry · bump version"]
    N --> O{Roadmap\ncomplete?}
    O -->|"More features"| I
    O -->|"All done"| P["<b>start_hardening</b><br/>Mutation tests · OWASP · load test"]
    P --> Q["🚢 Ship"]

    style A fill:#1a2e1a,color:#90ee90,stroke:#3a6e3a
    style Q fill:#1a2a3e,color:#87ceeb,stroke:#3a5a8e
    style E fill:#2e1a1a,color:#ffaa88,stroke:#6e3a3a
    style M fill:#2e2a00,color:#ffd700,stroke:#6e6000

ForgeCraft는 설정 시점 CLI 도구입니다. 프로젝트를 구성하기 위해 한 번 실행한 후 제거하면 됩니다 — 런타임 풋프린트가 없습니다.

선택적으로 MCP 센티널을 추가하여 AI 어시스턴트가 진단하고 명령을 추천하도록 할 수 있습니다:

claude mcp add forgecraft -- npx -y forgecraft-mcp

센티널은 단일 도구(~200 토큰)입니다. forgecraft.yaml, CLAUDE.md, .claude/hooks 세 가지 산출물을 읽고 올바른 다음 CLI 명령을 도출하여 반환합니다. 그 이상은 없습니다. 이것은 방법론의 핵심 원칙을 도구 설계로 표현한 것입니다: 무상태 리더, 유한한 산출물 세트, 도출된 액션. 초기 설정 후 제거하여 토큰 예산을 회수하세요.

제공되는 것

npx forgecraft-mcp setup 실행 후, 프로젝트에는 다음이 있습니다:

your-project/
├── forgecraft.yaml        ← Your config (tags, tier, customizations)
├── CLAUDE.md              ← Engineering standards (Claude)
├── .cursor/rules/         ← Engineering standards (Cursor)
├── .github/copilot-instructions.md  ← Engineering standards (Copilot)
├── Status.md              ← Session continuity tracker
├── .claude/hooks/         ← Pre-commit quality gates
├── docs/
│   ├── PRD.md             ← Requirements skeleton
│   └── TechSpec.md        ← Architecture + NFR sections
└── src/shared/            ← Config, errors, logger starters

지침 파일

이것이 핵심 가치입니다. 다음을 다루는 선별된 블록으로 조립됩니다:

  • SOLID 원칙 — 상투어가 아닌 구체적인 규칙

  • 헥사고날 아키텍처 — 포트, 어댑터, DTO, 레이어 경계

  • 테스팅 피라미드 — 단위/통합/E2E 목표, 테스트 더블 분류

  • 클린 코드 — CQS, 가드 절, 불변성, 순수 함수

  • CI/CD 및 배포 — 파이프라인 단계, 환경, 프리뷰 배포

  • 도메인 패턴 — DDD, CQRS, 이벤트 소싱 (프로젝트에 필요할 때)

  • 12-Factor 운영 — 구성, 무상태성, 폐기 가능성, 로깅

모든 블록은 확립된 엔지니어링 문헌(Martin, Evans, Wiggins)에서 출처를 얻어 AI 지원 개발에 맞게 조정되었습니다.

24개 태그 — AI 감지, 사용자 조정 가능

태그는 ForgeCraft에 프로젝트가 무엇인지 알려줍니다. 첫 설정 시 AI가 사양과 코드베이스를 분석하여 태그를 할당합니다. forgecraft.yaml에서 검토하고 재정의할 수 있습니다. 블록은 충돌 없이 병합됩니다 — 프로젝트가 발전함에 따라 태그를 추가하거나 제거하세요.

전체 태그 목록과 기여 가이드는 품질 게이트 저장소 →에 있습니다.

태그

추가되는 내용

UNIVERSAL

SOLID, 테스팅, 커밋, 오류 처리 (항상 활성화)

API

REST/GraphQL 계약, 인증, rate limiting, 버전 관리

WEB-REACT

컴포넌트 아키텍처, 상태 관리, 접근성, 성능 예산

WEB-STATIC

빌드 최적화, SEO, CDN, 정적 배포

CLI

인자 파싱, 출력 형식, 종료 코드

LIBRARY

API 설계, semver, 하위 호환성

INFRA

Terraform/CDK, Kubernetes, 시크릿 관리

DATA-PIPELINE

ETL, 멱등성, 체크포인팅, 스키마 진화

ML

실험 추적, 모델 버전 관리, 재현성

FINTECH

복식부기, 소수 정밀도, 규정 준수

HEALTHCARE

HIPAA, PHI 처리, 감사 로그, 암호화

MOBILE

React Native/Flutter, offline-first, 네이티브 API

REALTIME

WebSockets, presence, 충돌 해결

GAME

게임 루프, ECS, Phaser 3, PixiJS, Three.js/WebGL, 성능 예산

SOCIAL

피드, 연결, 메시징, 중재

ANALYTICS

이벤트 추적, 대시보드, 데이터 웨어하우징

STATE-MACHINE

전이, 가드, 이벤트 기반 워크플로

WEB3

스마트 계약, 가스 최적화, 지갑 보안

HIPAA

PII 마스킹, 암호화 검사, 감사 로깅

SOC2

접근 제어, 변경 관리, 사고 대응

DATA-LINEAGE

100% 필드 커버리지, 혈통 추적 데코레이터

OBSERVABILITY-XRAY

Lambda용 자동 X-Ray 계측

MEDALLION-ARCHITECTURE

Bronze=불변, Silver=검증됨, Gold=집계됨

ZERO-TRUST

기본 거부 IAM, 명시적 허용 규칙

콘텐츠 심층 등급

모든 프로젝트가 첫날부터 DDD를 필요로 하는 것은 아닙니다.

등급

포함 내용

적합한 대상

core

코드 표준, 테스팅, 커밋 프로토콜

신규/소규모 프로젝트

recommended

+ 아키텍처, CI/CD, 클린 코드, 배포

대부분의 프로젝트 (기본값)

optional

+ DDD, CQRS, 이벤트 소싱, 디자인 패턴

성숙한 팀, 복잡한 도메인

forgecraft.yaml에서 설정:

projectName: my-api
tags: [UNIVERSAL, API]
tier: recommended

CLI 명령어

npx forgecraft-mcp <command> [dir] [flags]

명령어

용도

setup <dir>

여기서 시작하세요. 분석 → 스택 자동 감지 → 지침 파일 + 훅 생성

refresh <dir>

프로젝트 변경 후 재스캔. 새 태그를 감지하고 변경 전후 diff를 표시합니다.

refresh <dir> --apply

새로고침 적용(기본값은 미리보기 전용)

audit <dir>

준수 점수(0-100) 산출. forgecraft.yaml에서 태그를 읽습니다.

scaffold <dir> --tags ...

전체 폴더 구조 + 지침 파일 생성

review [dir] --tags ...

구조화된 코드 리뷰 체크리스트(4가지 차원)

list tags

사용 가능한 24개 태그 모두 표시

list hooks --tags ...

지정된 태그에 대한 품질 게이트 훅 표시

list skills --tags ...

지정된 태그에 대한 스킬 파일 표시

classify [dir]

태그를 제안하도록 코드 분석

generate <dir>

지침 파일만 다시 생성

convert <dir>

레거시 코드를 위한 단계별 마이그레이션 계획

add-hook <name> <dir>

품질 게이트 훅 추가

add-module <name> <dir>

기능 모듈 스캐폴딩

공통 플래그

--tags UNIVERSAL API     Project classification tags (or read from forgecraft.yaml)
--tier core|recommended  Content depth (default: recommended)
--targets claude cursor  AI assistant targets (default: claude)
--dry-run                Preview without writing files
--compact                Strip explanatory bullet tails and deduplicate lines (~20-40% smaller output)
--apply                  Apply changes (for refresh)
--language typescript    typescript | python (default: typescript)
--scope focused          comprehensive | focused (for review)

MCP 센티널

선택적으로 ForgeCraft MCP 센티널을 추가하여 AI 어시스턴트가 프로젝트를 진단하고 올바른 CLI 명령어를 제안하도록 할 수 있습니다:

센티널은 단일 최소 도구입니다(요청당 약 200토큰, 전체 도구 모음의 약 1,500토큰 대비). forgecraft.yaml, AI 지침 파일, 훅이 존재하는지 확인한 다음 프로젝트의 현재 상태에 맞는 대상 CLI 명령어를 반환합니다.

이 설계는 의도적입니다. 전체 ForgeCraft 명령어 표면(21개 액션)은 MCP 서버가 아닌 CLI에 있습니다. MCP 서버는 세 가지 아티팩트를 읽고 하나의 권장 사항을 반환하는 정확히 하나의 도구만 노출합니다. 이것이 바로 도구 자체 아키텍처의 Generative Specification 원칙입니다: 상태 비저장 리더, 경계가 정해진 아티팩트 집합, 파생된 액션. 이 도구는 지침 파일에 작성하는 내용을 그대로 실천합니다.

부작용 하나: 선언된 모든 MCP 도구는 호출 여부와 관계없이 매 턴마다 모델에 의해 읽힙니다. 도구 하나는 200토큰이 듭니다. 21개 도구는 1,500토큰이 듭니다. 센티널은 방법론에서 권장하는 MCP 예산(활성 서버 ≤3개)을 설계상 유지합니다.

권장 워크플로:

  1. AI 어시스턴트에 센티널 추가(아래 설정 예시 참조)

  2. AI 어시스턴트가 npx forgecraft-mcp setup .을 실행하도록 함

  3. 활성 MCP 설정에서 센티널 제거

  4. 새로고침이나 감사가 필요할 때 다시 추가

.claude/settings.json에 추가:

{
  "mcpServers": {
    "forgecraft": {
      "command": "npx",
      "args": ["-y", "forgecraft-mcp"]
    }
  }
}

프로젝트 루트의 .vscode/mcp.json에 추가(없으면 생성):

{
  "servers": {
    "forgecraft": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "forgecraft-mcp"]
    }
  }
}

그런 다음 Copilot Chat 패널을 열고 Agent 모드로 전환하면 도구 목록에 forgecraft 센티널이 나타납니다.

.cursor/mcp.json에 추가:

{
  "mcpServers": {
    "forgecraft": {
      "command": "npx",
      "args": ["-y", "forgecraft-mcp"]
    }
  }
}

MCP 클라이언트가 없나요? 괜찮습니다 — 필요하지 않습니다. 터미널에서 npx forgecraft-mcp setup .을 직접 실행하세요. MCP 센티널은 선택 사항입니다. CLI가 모든 것을 처리합니다.

이미 claude init을 실행했나요? 기존 CLAUDE.md와 병합하려면 npx forgecraft-mcp generate . --merge를 사용하세요. 사용자 지정 섹션을 유지하면서 프로덕션 표준을 추가합니다.


무료 및 오픈 소스

ForgeCraft는 무료입니다. 제한 없음, 등급 없음, API 키 없음.

품질 게이트 라이브러리는 커뮤니티 기여를 통해 성장합니다. 게이트를 제안하여 승인되면 CONTRIBUTORS.md에 이름이 오르고, AI로 구축하는 모든 사람을 위한 최소 기준을 높이는 데 기여하게 됩니다.

게이트 제안 열기 → · 기여자 보기 →

팀과 함께 사용 중이신가요? → forgeworkshop.dev


이론적 기반

ForgeCraft는 Generative Specification 모델을 구현합니다 — AI 생성 코드 품질을 평가하기 위한 공식 7속성 프레임워크입니다. 모델, S_realized 수렴 공식, 릴리스 단계 프레임워크는 백서에 문서화되어 있습니다.

Generative Specification: A Discipline of Derivability for the Stateless Reader — Zenodo (V4.0, 2026). 오픈 액세스, DOI: 10.5281/zenodo.21726017. verify 점수의 학술적 기반입니다.

백서는 이론입니다. ForgeCraft는 도구 체인입니다. 라이브러리에 제안된 품질 게이트 중 이론적 통찰로 일반화할 수 있는 것은 향후 백서 개정판에 통합될 수 있습니다.

업계 맥락: Spec-Driven Development 수렴(ThoughtWorks Tech Radar 2025 "Adopt"; Addy Osmani / Google Cloud AI agent-skills)은 실무자 운동입니다. Generative Specification은 그 실천이 무엇이고 왜 작동하는지를 명명하는 공식 모델입니다.


GS 하네스 — AI 어시스턴트를 위한 입문서

ForgeCraft는 Generative Specification (GS) 을 구현합니다. 이 섹션은 이 파일을 읽는 AI 어시스턴트를 위해 작성되었습니다: GS가 무엇인지, 제대로 스캐폴딩된 하네스가 어떤 모습인지, 무엇을 확인해야 하는지 설명합니다.

핵심 제약 — 상태 비저장 리더

모든 AI 세션은 이전 세션의 기억, 공유 컨텍스트, 누적된 규칙, 명확한 질문을 할 수 있는 능력 없이 시작됩니다. 아티팩트에 없는 모든 것은 부재합니다.

GS는 이를 결함이 아닌 설계 제약으로 취급합니다. 파생 가능성(Derivability) — 새 AI 인스턴스가 아티팩트만으로 올바르게 결정할 수 있는 것 — 은 사양이 충족해야 하는 기준입니다. 상태 비저장 리더가 아티팩트에서 올바른 출력을 파생할 수 없다면, 사양이 불완전한 것이지 AI의 잘못이 아닙니다.

센티널 시스템

아키텍처 헌법(CLAUDE.md, .cursor/rules/, .github/copilot-instructions.md, .windsurfrules)은 모든 AI 세션의 진입점입니다. 이 헌법에는 집합적으로 다섯 가지 필수 범주가 포함되어야 합니다:

범주

다루는 내용

아키텍처 정체성

시스템이 무엇인지, 범위 경계, ADR 색인

표준

명명 규칙, 커밋 규율, 품질 게이트 임계값

제약 및 금지 사항

절대 일어나서는 안 되는 것; AI가 거부해야 하는 계층 위반

도구 순서 지정

어떤 도구를 어떤 순서로 언제 사용할지 — "이런 도구가 존재한다"가 아니라 "C일 때 X 다음에 Y를 사용"

라우팅

각 하위 사양 파일이 다루는 내용과 언제 그 안으로 내려가야 하는지

도구 순서 지정은 가장 흔히 누락되는 범주이자 가장 결과가 큰 공백입니다. 도구를 나열하면서 언제 어떤 것을 선호해야 하는지 명시하지 않는 사양은 매 세션마다 신뢰할 수 없는 추론을 강제합니다.

센티널은 탐색 트리입니다: 루트는 항상 로드되고, 각 하위 노드는 자체 범위와 라우팅 조건을 선언하며, AI는 현재 작업과 관련된 분기로만 내려갑니다. 모든 잎을 결합하면 완전한 사양이 됩니다 — 무손실입니다. 이 설계는 컨텍스트 비대와 관련 없는 콘텐츠 로드로 인한 정확도 저하를 방지합니다.

브리지 — 탐색 정책으로서의 구조적 규율

SOLID, 헥사고날 아키텍처, TDD는 단순한 엔지니어링 규율이 아닙니다 — GS 프로젝트에서는 적극적인 탐색 정책이 됩니다:

  • 구현보다 인터페이스를 먼저 읽는다. 포트/어댑터 경계가 깔끔하면 인터페이스가 계약이다. 계약이 충분하지 않은 경우에만 구현을 건너뛴다.

  • 통과한 테스트를 신뢰한다. TDD가 강제되면 통과하는 테스트 스위트는 올바른 동작의 증거이다. 이를 검증하기 위해 구현을 읽을 필요가 없다.

  • ADR이 이유이다. 모든 비자명한 결정이 기록되면 AI는 코드에서 의도를 추론하는 대신 기록을 읽는다.

이 다리는 이전 규율의 수동적 구조적 이점을 토큰 사용량과 컨텍스트 소비의 측정 가능한 감소로 전환한다.

토큰 정리

컨텍스트 창 크기와 위치 배치는 모두 AI 정확도를 저하시킨다(Liu et al., 2023). GS는 설계상 불필요한 토큰 소비를 최소화한다:

  • 센티널 트리는 지연 로딩된다. 작업당 관련 분기만 로드된다 — 전체 사양이 한 번에 로드되지 않는다.

  • 구현보다 계약. 인터페이스, 스키마 정의, 테스트 어서션이 먼저 읽힌다. 구현 파일은 계약만으로 답을 도출할 수 없을 때만 읽힌다.

  • 컨스티튜션은 모든 세션을 이끈다. 가장 중요한 콘텐츠는 위치 정확도가 가장 높은 컨텍스트의 선두 위치를 차지한다.

  • MCP 도구 표면은 제한적이다. 선언된 각 MCP 도구는 호출 여부와 관계없이 매 턴마다 모델에 의해 읽힌다. ForgeCraft 센티널은 전체 명령 표면(~1,500 토큰) 대신 하나의 도구(~200 토큰)를 노출한다. 이 도구는 프로젝트에 작성하는 방법론을 실천한다.

문서 분류 — 완전한 GS 프로젝트가 포함하는 것

스캐폴딩된 프로젝트에는 이러한 아티팩트 유형이 포함된다. 누락된 것이 있으면 하네스가 불완전하다:

아티팩트

표준 경로

역할

아키텍처 컨스티튜션

CLAUDE.md · .cursor/rules/ · .windsurfrules · .github/copilot-instructions.md

모든 AI 세션 시작 시 로드되는 지배 규칙

문서 매니페스트

docs/manifest.yaml

어떤 아티팩트 유형이 어디에 존재하는지 선언 — 분류 계약

세션 연속성

docs/status.md

현재 상태, 진행 중인 작업, 최근 결정 — 각 세션마다 업데이트

기능 사양

docs/PRD.md

사용자 대상 동작, 도메인 모델, 시스템 경계

아키텍처 문서

docs/TechSpec.md

계층 구조, 모듈 경계, 통합 표면(C4 다이어그램 포함)

결정 기록

docs/adrs/NNNN-slug.md

비자명한 아키텍처 선택당 하나, MADR 형식

사용 사례

docs/use-cases/

동작 계약 — 동시에 테스트 사양

스키마

docs/specs/

데이터 모델, API 계약, 공식 제약 조건이 있는 이벤트 스키마

프로젝트 구성

forgecraft.yaml

태그, 티어, 대상 — ForgeCraft 진입점

초기화 캐스케이드: 사양은 순서대로 생성된다 — 각각은 앞선 것의 출력이자 뒤따르는 것의 생성 규칙이다. 기능 사양 → 아키텍처 → 컨스티튜션 → ADR → 사용 사례. 상태 비저장 에이전트가 다섯 가지 아티팩트 세트를 모두 받았을 때 추가적인 인간 지시 없이 유효한 구현 상태를 도출할 수 있으면 캐스케이드가 완료된 것이다.

7가지 속성 — 검증할 사항

제대로 스캐폴딩된 GS 프로젝트는 일곱 가지를 모두 충족한다. 이는 verify 명령이 점수를 매기는 속성이다:

속성

검증 내용

자기 설명적

코드베이스가 자체 아티팩트에서 자체 아키텍처, 결정, 규칙을 설명한다 — 외부 지식 불필요

경계 있음

모든 단위에 명시적 범위와 이음새가 있다; 비즈니스 로직이 계층 경계를 넘어 누출되지 않는다

검증 가능

정확성을 인간의 판단 없이 확인할 수 있다 — 타입, 테스트, 커버리지 게이트, 스키마 계약

방어됨

파괴적 작업이 단순히 권장되지 않고 구조적으로 방지된다 — 커밋 훅, 브랜치 보호, 형식 강제

감사 가능

현재 상태와 이력을 아티팩트만으로 완전히 복구할 수 있다 — 기존 커밋, ADR

구성 가능

단위가 예상치 못한 결합 없이 결합 및 확장된다 — 의존성 역전, 순수 함수 모델

실행 가능

출력이 실제 실행 환경에서 실행될 때 동작 계약을 충족한다 — 컴파일만 되는 것이 아니라


구성

AI 어시스턴트가 보는 것을 미세 조정

# forgecraft.yaml
projectName: my-api
tags: [UNIVERSAL, API, FINTECH]
tier: recommended
outputTargets: [claude, cursor, copilot]  # Generate for multiple assistants
compact: true                             # Slim output (~20-40% fewer tokens)

exclude:
  - cqrs-event-patterns    # Don't need this yet

variables:
  coverage_minimum: 90      # Override defaults
  max_file_length: 400

커뮤니티 템플릿 팩

templateDirs:
  - ./my-company-standards
  - node_modules/@my-org/forgecraft-flutter/templates

표준을 최신으로 유지

감사 (언제든지 또는 CI에서 실행)

Score: 72/100  Grade: C

✅ Instruction files exist
✅ Hooks installed (3/3)
✅ Test script configured
🔴 hardcoded_url: src/auth/service.ts
🔴 status_md_current: not updated in 12 days
🟡 lock_file: not committed

새로 고침 (프로젝트 범위가 변경되었습니까?)

npx forgecraft-mcp refresh . --apply

또는 먼저 미리 보기 모드에서 (기본값):

npx forgecraft-mcp refresh .   # shows before/after diff without writing

기여

템플릿은 코드가 아닌 YAML이다. TypeScript를 작성하지 않고도 패턴을 추가할 수 있다.

templates/your-tag/
├── instructions.yaml   # Instruction file blocks (with tier metadata)
├── structure.yaml      # Folder structure
├── nfr.yaml            # Non-functional requirements
├── hooks.yaml          # Quality gate scripts
├── review.yaml         # Code review checklists
└── mcp-servers.yaml    # Recommended MCP servers for this tag

PR 환영합니다. 형식은 templates/universal/를 참조하세요.

MCP 서버 검색

npx forgecraft-mcp configure-mcp는 프로젝트 태그와 일치하는 권장 MCP 서버를 동적으로 검색한다. 서버는 태그별로 mcp-servers.yaml에 큐레이션되어 있으며 — PR을 통해 커뮤니티 기여가 가능하다.

기본 권장 사항에는 Context7(문서), Playwright(테스트), Chrome DevTools(디버깅), Stripe(핀테크), Docker/K8s(인프라) 등 24개 태그 전반에 걸친 항목이 포함된다.

선택적으로 설정 시 원격 레지스트리에서 가져올 수 있다:

# In forgecraft.yaml or via tool parameter
include_remote: true
remote_registry_url: https://your-org.com/mcp-registry.json

개발

git clone https://github.com/jghiringhelli/forgecraft-mcp.git
cd forgecraft-mcp
npm install
npm run build
npm test   # 610 tests, 42 suites

라이선스

MIT


Generative Specification의 일부

Generative Specification (GS) 뒤에 있는 무료 도구 — 표류하지 않는 AI로 소프트웨어를 구축하는 규율: 상태 비저장 AI가 올바른 코드를 도출할 수 있을 만큼 정밀한 사양을 작성하고, 하네스가 라이브 시스템에 대해 이를 검증한다.

A
license - permissive license
Not graded
quality - not tested
A
maintenance

Maintenance

Maintainers
Response time
0dRelease cycle
2Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI coding agents to generate standardized code using scaffolding templates, enforce architectural patterns, and validate outputs programmatically. Supports creating projects from boilerplates and adding features to existing codebases while maintaining team conventions.
    160
    AGPL 3.0
  • F
    license
    A
    quality
    D
    maintenance
    Provides real-time policy enforcement for AI coding agents by intercepting and validating their actions against organizational standards like naming conventions, security policies, and compliance rules before execution. Prevents violations through immediate feedback and auto-correction suggestions.
    5

View all related MCP servers

Related MCP Connectors

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jghiringhelli/forgecraft-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server