Claude Code 신규 서버용 프롬프트 개선: 프로젝트 타입별 모듈 자동 선택과 C++/서버 프로젝트 최적화 가이드

Claude Code 프로젝트 하네스 개선 가이드

신규 서버용 프롬프트 개선하기
프로젝트 타입별로 필요한 모듈만 생성하는 구조

UI가 없는 C++ 서버, CLI, 라이브러리 프로젝트에 DESIGN.md, ui-improve, ux-improve 같은 UI 전용 파일이 불필요하게 생성되는 문제를 막기 위해, 프로젝트 타입을 먼저 감지하고 필요한 모듈만 활성화하는 방식으로 프롬프트를 개선하는 방법을 정리했다.

핵심 요약

• 모든 프로젝트에 동일한 commands, skills, rules를 생성하지 않는다.
• 프로젝트 타입을 먼저 감지한 뒤 필요한 모듈만 생성한다.
• UI가 없는 프로젝트에는 DESIGN.md와 UI/UX 관련 command, skill을 만들지 않는다.
• C/C++ 프로젝트는 native-build, native-debug, memory-check 중심으로 구성한다.
• CLAUDE.md 라우팅 표도 활성화된 모듈만 포함하도록 만든다.

목차

1. 왜 프로젝트 타입 감지가 필요한가?
2. 전체 구조: Core + 선택 모듈
3. 프로젝트 타입별 생성 정책
4. 신규 서버용 프롬프트에 추가할 핵심 블록
5. C/C++ 프로젝트 전용 규칙
6. UI 없는 C++ 프로젝트 적용 예시
7. 최종 정리

1. 왜 프로젝트 타입 감지가 필요한가?

Claude Code용 프로젝트 하네스를 만들 때, 모든 프로젝트에 같은 파일을 생성하면 편해 보이지만 실제로는 불필요한 context가 늘어난다. 특히 UI가 없는 C++/CLI/서버/라이브러리 프로젝트에 DESIGN.md, ui-improve, ux-improve, design-sync, ui-ux-review 같은 파일이 생성되면 프로젝트 목적과 맞지 않는 문맥이 계속 섞이게 된다.

문제점

UI가 없는 프로젝트에 UI 관련 규칙이 들어가면 Claude가 작업 방향을 잘못 잡거나, 검토 대상이 아닌 파일까지 고려하게 된다. 결과적으로 응답 품질이 떨어지고 프로젝트 구조도 불필요하게 커진다.

따라서 신규 서버용 기본 프롬프트는 하네스 파일을 만들기 전에 프로젝트 타입을 먼저 감지하고, 감지 결과에 따라 필요한 모듈만 설치하도록 바꾸는 것이 좋다.

2. 전체 구조: Core + 선택 모듈

기본 구조는 단순하다. 모든 프로젝트에 필요한 Core 모듈은 항상 생성하고, UI, DB, API, Native, Script/Data 같은 모듈은 프로젝트에서 실제로 필요한 경우에만 생성한다.

공통 Core Harness
  항상 생성

UI Module
  UI 프로젝트일 때만 생성

DB Module
  DB 또는 migration이 있을 때만 생성

API Module
  API, client, server 구조가 있을 때만 생성

Native/C++ Module
  C 또는 C++ 프로젝트일 때 생성

Docs/Wiki
  항상 생성하되, 프로젝트 타입별 섹션만 활성화

이렇게 구성하면 웹 프론트엔드, 백엔드 API, C++ 서버, CLI 도구, 라이브러리, 배치 작업 프로젝트에 모두 적용할 수 있다. 중요한 점은 “모든 것을 미리 깔아두는 방식”이 아니라 “필요한 것만 활성화하는 방식”으로 바꾸는 것이다.

3. 프로젝트 타입별 생성 정책

프로젝트 타입에 따라 생성할 파일과 생략할 파일을 명확히 나누면 Claude Code가 더 정확하게 동작한다.

프로젝트 타입	생성할 것	생략할 것
웹 UI / 프론트엔드	DESIGN.md, ui/ux commands, design skills	없음
WPF / WinForms / Qt UI	DESIGN.md, ui/ux commands, design skills	웹 전용 규칙
백엔드 API	api, db-schema, performance, security	DESIGN.md 선택, ui/ux 생략
C++ CLI / 데몬 / 라이브러리	native-build, native-debug, memory-check, performance, test	DESIGN.md, ui/ux, design-sync 생략
DB 중심 프로젝트	db-schema, migration guard	UI 관련 생략
문서 / 스크립트 프로젝트	plan, verify, docs-sync, review	UI/API/DB 관련 대부분 생략

4. 신규 서버용 프롬프트에 추가할 핵심 블록

아래 내용은 기존 프롬프트의 “프로젝트 내부 하네스 구조 생성” 전에 넣으면 좋다. 핵심은 하네스 파일을 만들기 전에 프로젝트 타입을 감지하고, 필요한 모듈만 생성하도록 강제하는 것이다.

추가 위치

기존 프롬프트에서 파일 생성 목록이 나오기 전에 배치한다. 그래야 Claude가 모든 commands와 skills를 무조건 생성하지 않고, 먼저 프로젝트 타입을 판단하게 된다.

4-1. 프로젝트 타입 감지 규칙

────────────────────────────────────────
2-A. 프로젝트 타입 감지 및 모듈 선택
────────────────────────────────────────

하네스 파일을 만들기 전에 프로젝트 타입을 먼저 감지한다.
모든 commands/skills를 무조건 생성하지 않는다.
프로젝트에 필요한 모듈만 생성한다.

감지 기준:

1. Web UI / Frontend
   - package.json 존재
   - src/components, pages, app, routes, views 존재
   - React, Vue, Angular, Svelte, Next, Vite, Webpack 등 확인
   - CSS/SCSS/Tailwind/theme 파일 존재

2. Desktop UI
   - WPF/WinForms/MAUI/Qt/Electron 관련 파일 존재
   - App.xaml, ResourceDictionary, *.ui, qml, electron 설정 등 확인

3. Backend API / Server
   - controllers, routes, api, server, handlers, services 존재
   - Spring, Express, FastAPI, ASP.NET, NestJS 등 확인
   - OpenAPI/Swagger, REST, gRPC 관련 파일 확인

4. DB / Migration
   - migrations, schema, prisma, sql, entity, model, repository 존재
   - Flyway, Liquibase, Prisma, TypeORM, Alembic, EF migration 등 확인

5. Native C/C++
   - CMakeLists.txt, Makefile, configure, .vcxproj, .sln 존재
   - src/*.cpp, include/*.h, include/*.hpp 존재
   - vcpkg, Conan, CMakePresets.json 존재

6. CLI / Daemon / Service
   - main.cpp, main.c, argparse/CLI parser, systemd/service config, daemon entrypoint 확인
   - UI 관련 파일이 없고 콘솔/서비스 실행 구조인 경우

7. Library / SDK
   - include/, lib/, src/ 중심 구조
   - public API header, tests/, examples/ 존재
   - 실행 앱보다 재사용 라이브러리 성격이 강한 경우

8. Script / Data job
   - scripts/, notebooks/, jobs/, pipelines 존재
   - Python, shell, ETL, batch 중심

프로젝트 타입은 하나 이상 선택할 수 있다.
예: C++ server + DB, Web frontend + API client, Desktop UI + native module.

감지 결과를 프로젝트 wiki Overview에 기록한다.

| 항목 | 내용 | 근거 |
|---|---|---|
| 프로젝트 타입 | | |
| 활성 모듈 | | |
| 비활성 모듈 | | |
| 판단 근거 | | |

4-2. 모듈별 생성 정책

────────────────────────────────────────
2-B. 모듈별 생성 정책
────────────────────────────────────────

항상 생성하는 Core 모듈:

- CLAUDE.md
- .claude/settings.json
- .claude/mcp.md
- .claude/permissions.md
- .claude/hooks.md
- .claude/rules/coding.md
- .claude/rules/git.md
- .claude/rules/review.md
- .claude/rules/verification.md
- .claude/commands/README.md
- .claude/commands/plan.md
- .claude/commands/bugfix.md
- .claude/commands/refactor.md
- .claude/commands/performance.md
- .claude/commands/security.md
- .claude/commands/test.md
- .claude/commands/verify.md
- .claude/commands/sync-docs.md
- .claude/commands/log-error.md
- .claude/commands/review.md
- .claude/commands/release-check.md
- .claude/skills/README.md
- .claude/skills/command-router/SKILL.md
- .claude/skills/error-logger/SKILL.md
- .claude/skills/verify-loop/SKILL.md
- .claude/skills/regression-check/SKILL.md
- .claude/agents/README.md
- .claude/wiki/**

UI 모듈은 UI 프로젝트에서만 생성한다:

- DESIGN.md
- .claude/rules/ui.md
- .claude/commands/ui-improve.md
- .claude/commands/ux-improve.md
- .claude/skills/design-sync/SKILL.md
- .claude/skills/ui-ux-review/SKILL.md
- .claude/wiki/patterns/design-system.md
- .claude/wiki/patterns/ui-rules.md

UI 프로젝트가 아니면:
- DESIGN.md를 생성하지 않는다.
- ui-improve, ux-improve command를 생성하지 않는다.
- design-sync, ui-ux-review skill을 생성하지 않는다.
- CLAUDE.md 라우팅 표에도 UI 관련 행을 넣지 않는다.
- 단, 나중에 UI가 추가될 수 있으면 wiki에 "UI module inactive"만 기록한다.

API 모듈은 API 관련 구조가 있을 때만 생성한다:

- .claude/commands/api.md
- .claude/skills/api-contract-check/SKILL.md

DB 모듈은 schema/migration이 있을 때만 생성한다:

- .claude/commands/db-schema.md
- .claude/skills/db-change-guard/SKILL.md

Native C/C++ 모듈은 C/C++ 프로젝트에서 생성한다:

- .claude/commands/native-build.md
- .claude/commands/native-debug.md
- .claude/commands/memory-check.md
- .claude/rules/native.md
- .claude/skills/native-build-guard/SKILL.md
- .claude/skills/debug-symbol-check/SKILL.md

Script/Data 모듈은 scripts/jobs/pipelines 중심 프로젝트에서 생성한다:

- .claude/commands/data-flow.md
- .claude/commands/pipeline-check.md
- .claude/skills/pipeline-guard/SKILL.md

5. C/C++ 프로젝트 전용 규칙

C/C++ 프로젝트로 감지되면 UI 관련 문서는 만들지 않고, 빌드, 디버깅, 메모리 안정성 중심으로 구성하는 것이 좋다. 특히 C++ 프로젝트는 빌드 시스템, 컴파일러, ABI, 플랫폼 차이, 메모리 소유권, 스레드 이슈를 무리하게 추정하면 위험하다.

────────────────────────────────────────
2-C. C/C++ 프로젝트 전용 규칙
────────────────────────────────────────

C/C++ 프로젝트로 감지되면 UI 관련 문서는 만들지 말고, 아래를 만든다.

.claude/rules/native.md:

# Native C/C++ Rules

## 기본 원칙

- 빌드 시스템을 먼저 확인한다: CMake, Make, MSBuild, Ninja, Bazel, Meson.
- 컴파일러와 표준 버전을 확인한다: gcc, clang, MSVC, C++17/20/23.
- ABI, platform, architecture 차이를 추정하지 않는다.
- 경고를 무시하지 않는다.
- undefined behavior 가능성이 있는 변경은 계획을 먼저 제시한다.
- public header 변경 시 ABI/API 영향을 기록한다.
- raw pointer 소유권 변경은 명시적으로 설명한다.
- 메모리/스레드/락 관련 변경은 최소 변경 후 검증한다.

## 금지

- 빌드 설정 대량 변경 금지
- compiler flag 임의 변경 금지
- warning suppress 임의 추가 금지
- public API header 임의 변경 금지
- thread sleep으로 race condition 숨기기 금지
- 테스트 약화 금지

.claude/commands/native-build.md:

# /native-build

## 목적

C/C++ 프로젝트의 빌드 시스템과 빌드 명령을 확인하고 최소 검증을 수행한다.

## 먼저 읽을 문서

- CLAUDE.md
- .claude/rules/native.md
- .claude/wiki/projects/<project-slug>.md
- CMakeLists.txt 또는 Makefile 또는 .sln/.vcxproj

## 절차

1. 빌드 시스템을 확인한다.
2. 기존 빌드 명령을 wiki에서 확인한다.
3. 없으면 README와 설정 파일에서 확인한다.
4. 새 빌드 명령을 추정하지 않는다.
5. 가능한 최소 빌드 검증만 제안하거나 실행한다.
6. 실패 시 verify-loop를 사용한다.

## 출력 형식

| 항목 | 내용 |
|---|---|
| 빌드 시스템 | |
| 빌드 명령 | |
| 검증 결과 | |
| 실패 원인 | |
| 다음 조치 | |

.claude/commands/native-debug.md:

# /native-debug

## 목적

C/C++ 런타임 오류, crash, segmentation fault, access violation, deadlock, race condition을 분석한다.

## 먼저 읽을 문서

- .claude/rules/native.md
- .claude/wiki/troubleshooting/troubleshooting-index.md
- 관련 crash log 또는 stack trace
- 관련 source/header 파일

## 절차

1. 증상과 재현 조건을 정리한다.
2. stack trace가 있으면 먼저 분석한다.
3. 포인터 소유권, lifetime, bounds, thread interaction을 확인한다.
4. 최소 수정 계획을 제시한다.
5. 수정 후 가능한 검증 방법을 제안한다.
6. 해결 후 error-logger를 사용한다.

## 출력 형식

| 항목 | 내용 |
|---|---|
| 증상 | |
| 원인 후보 | |
| 관련 파일 | |
| 수정 계획 | |
| 검증 방법 | |
| 재발 방지 | |

.claude/commands/memory-check.md:

# /memory-check

## 목적

C/C++ 메모리 안전성 문제를 점검한다.

## 먼저 읽을 문서

- .claude/rules/native.md
- 관련 source/header 파일
- 테스트 또는 재현 절차

## 점검 항목

- use-after-free
- double free
- out-of-bounds
- dangling pointer/reference
- ownership ambiguity
- data race
- uninitialized memory
- RAII 위반

## 출력 형식

| 항목 | 내용 |
|---|---|
| 위험 유형 | |
| 관련 코드 | |
| 근거 | |
| 수정 제안 | |
| 검증 방법 | |

Native Skill 후보:

native-build-guard:
- 빌드 시스템, compiler flag, target 변경 시 사용
- 빌드 설정 대량 변경 방지
- platform/architecture 영향 확인

debug-symbol-check:
- crash 분석, stack trace 분석, release/debug symbol 확인 시 사용
- 심볼 누락, 최적화 빌드, line info 유무 확인

6. UI 없는 C++ 프로젝트 적용 예시

이 구조가 적용되면 UI 없는 C++ 프로젝트에는 아래처럼 필요한 파일만 생성되어야 한다. 핵심은 Native 관련 command와 skill은 생성하고, UI/DESIGN 관련 파일은 생략하는 것이다.

생성됨

• CLAUDE.md
• .claude/rules/coding.md
• .claude/rules/native.md
• .claude/rules/verification.md
• .claude/commands/native-build.md
• .claude/commands/native-debug.md
• .claude/commands/memory-check.md
• .claude/commands/bugfix.md
• .claude/commands/verify.md
• .claude/skills/native-build-guard/SKILL.md
• .claude/skills/debug-symbol-check/SKILL.md
• .claude/wiki/...

생략됨

• DESIGN.md
• .claude/rules/ui.md
• .claude/commands/ui-improve.md
• .claude/commands/ux-improve.md
• .claude/skills/design-sync
• .claude/skills/ui-ux-review

적용 포인트

C++ 서버나 CLI 프로젝트는 UI 개선보다 빌드 재현성, 디버깅 가능성, 메모리 안정성, 테스트 검증이 더 중요하다. 따라서 Claude Code의 작업 모드도 native-build, native-debug, memory-check 중심으로 잡아야 한다.

7. 최종 정리

기존 프롬프트의 핵심 문장을 아래 방향으로 바꾸면 된다.

모든 프로젝트에 동일한 commands/skills를 생성하지 않는다.
프로젝트 타입을 먼저 감지하고 활성 모듈만 생성한다.
UI가 없는 프로젝트에는 UI/DESIGN 관련 파일을 만들지 않는다.
C/C++ 프로젝트에는 native-build/native-debug/memory-check 중심으로 구성한다.

이렇게 바꾸면 웹 프로젝트, WPF, 백엔드, C++ CLI, 라이브러리, 배치 서버 어디에 적용해도 과한 파일이 생기지 않는다. Claude Code가 프로젝트 성격에 맞는 문맥만 읽게 되므로 작업 정확도도 좋아지고, 불필요한 context 낭비도 줄어든다.

결론

신규 서버용 프롬프트는 “많이 생성하는 프롬프트”가 아니라 “정확히 필요한 것만 생성하는 프롬프트”가 되어야 한다. 특히 UI 없는 C++/서버 프로젝트에서는 DESIGN/UI 계열을 과감히 비활성화하고, Native 빌드, 디버깅, 메모리 안정성 중심으로 하네스를 구성하는 것이 가장 안전하다.