Code Health MCP (CodeScene)
AI 기반 코딩을 위한 구조적 유지보수성 피드백입니다. 스타일/린트 스킬(coding-standards, plankton-code-quality)을 설계 수준의 건강 점수 및 회귀 게이트로 보완합니다.
상위 저장소: codescene-oss/codescene-mcp-server
패키지: @codescene/codehealth-mcp (stdio via npx)
보안 및 경계
옵트인 (ECC): mcp-configs/mcp-servers.json의 codescene 블록은 템플릿일 뿐입니다. ECC 플러그인 설치는 번들된 MCP 서버를 자동 활성화하지 않습니다. 원하는 경우에만 해당 항목을 설정에 복사하세요. ECC_DISABLED_MCPS=codescene,...을 사용하여 ECC 설치/동기화 중에 제외할 수 있습니다.
자격 증명: 번들된 토큰은 없습니다. CS_ACCESS_TOKEN을 직접 설정하세요 (상위 저장소의 getting-a-personal-access-token.md 참조). 토큰을 저장소에 커밋하지 마세요.
도구가 읽는 항목: 호출 시 도구는 사용자가 지정한 로컬 저장소의 파일과 git 상태를 분석합니다 (전달한 경로 및 analyze_change_set의 브랜치 컨텍스트). 자체적으로 실행되지는 않습니다. 독립 실행 모드의 경우 상위 저장소의 개인정보 보호 문서(codescene-mcp-server README 및 CodeScene 정책)를 따르세요. 이 스킬을 비밀, 자격 증명 또는 분석을 원하지 않는 경로에 사용하지 마세요.
MCP를 사용할 수 없는 경우 (오프라인, 잘못된 토큰, 서버 충돌): Code Health 점수를 임의로 생성하지 마세요. 사용자에게 검사가 생략되었음을 알리세요. 명시적인 사용자 승인 없이 계속 진행하지 마세요. MCP가 다운된 경우 게이팅에는 린트/테스트/검증 루프를 우선 사용하세요. 서버가 연결되면 검사를 다시 활성화하세요.
사용 시기
- 사용자가 코드 품질 검토, 파일 리팩토링 또는 AI 변경으로 유지보수성 저하 여부 확인을 요청할 때
- 핫스팟, 레거시 모듈 또는 익숙하지 않은 파일을 편집하기 전
- 유지보수성 보호 장치가 필요한 커밋 또는 풀 리퀘스트 전
- 대규모 에이전트 작성 diff 후 Code Health 회귀 여부 확인
- 구조적 검사(테스트/린트 대체 아님)로
verification-loop,tdd-workflow또는/quality-gate와 함께 사용
활성화 시기
위의 사용 시기와 동일한 트리거입니다. 이 제목은 ECC가 스킬 자동 활성화에 사용합니다.
작동 방식
1. MCP 서버 연결
mcp-configs/mcp-servers.json에서 codescene 항목을 사용 중인 MCP 설정에 복사하세요.
Claude Code (~/.claude.json → mcpServers):
"codescene": {
"command": "npx",
"args": ["-y", "@codescene/codehealth-mcp"],
"env": {
"CS_ACCESS_TOKEN": "YOUR_CS_ACCESS_TOKEN_HERE"
}
}
프로젝트 범위: 동일한 블록을 저장소 루트의 .mcp.json에 병합하세요.
토큰 설정은 상위 저장소(위 링크)에 문서화되어 있습니다. 독립 실행 모드는 아래 나열된 네 가지 도구에 대해 유료 CodeScene 플랫폼 계정이 필요하지 않습니다. 세션을 다시 시작하고 점수에 의존하기 전에 codescene 서버가 연결되었는지 확인하세요.
2. 독립 실행 도구만 호출
| 도구 | 사용 시기 |
|---|---|
code_health_review | 파일을 수정하기 전 전체 구조 분석 |
code_health_score | 각 변경 후 빠른 숫자 점수 (델타 확인) |
pre_commit_code_health_safeguard | Code Health 회귀를 유발하는 커밋 차단 |
analyze_change_set | PR을 열기 전 브랜치 수준 검사 |
플랫폼 전용 도구(예: 저장소 전체 기술 부채 핫스팟 목록)를 호출하지 마세요. delta_analysis를 참조하지 마세요. 독립 실행 모드에서 사용할 수 없습니다.
3. 점수 해석 (1–10)
| 범위 | 의미 | 에이전트 동작 |
|---|---|---|
| 9.0–10.0 | 녹색 — 건강함 | 확장해도 안전하지만 여전히 수직 슬라이스 선호 |
| 4.0–8.9 | 노란색 — 부채 있음 | 신중하게 접근; 우회 리팩토링 금지 |
| 1.0–3.9 | 빨간색 — 심각한 부채 | 범위를 좁게만 유지 |
4. 피드백 루프 실행
파일을 건드리기 전
- 대상 경로에서
code_health_review를 실행합니다. - 기준 점수와 나열된 코드 스멜을 기록합니다.
- 작업을 처리하는 가장 작은 변경을 계획합니다.
점수별 범위: 5 미만 — 최소 diff만; 5–7 — 광범위한 리팩토링 금지; 7 초과 — 리팩토링해도 더 안전하지만 각 편집 후 여전히 확인 필요.
각 변경 후
- 동일한 파일에서
code_health_score를 실행합니다. code_health_review의 기준과 비교합니다.- 점수가 회귀되었다면 계속 진행하기 전에 수정하세요. 시작했을 때보다 점수가 낮은 상태에서 작업을 완료로 표시하지 마세요.
모든 커밋 전 — 저장소 경로에서 pre_commit_code_health_safeguard를 실행합니다.
PR 전 — 기본 브랜치(예: main)를 대상으로 analyze_change_set을 실행합니다.
예제
예제: Flask 유지보수성 개선
pallets/flask에서 독립 실행 도구만 사용하는 에이전트 루프:
- 대상 모듈에서
code_health_review실행 (기준 4.82) - 나열된 스멜을 해결하는 목표 지향 리팩토링
- 각 편집 후
code_health_score실행 - 커밋 전
pre_commit_code_health_safeguard실행 - PR 전
analyze_change_set실행
결과: Code Health 4.82 → 9.1 (무료 독립 실행 토큰만 사용).
예제: AGENTS.md 적용 블록
프로젝트 AGENTS.md 또는 CLAUDE.md에 붙여넣기:
## Code Health (CodeScene MCP)
파일을 수정하기 전: `code_health_review`를 실행하고 점수와 문제점을 기록합니다.
- 점수가 5 미만: 문제 영역 — 변경 범위를 좁게 유지합니다.
- 점수가 5–7: 경고 영역 — 광범위한 리팩토링을 하지 마세요.
각 변경 후: `code_health_score`를 실행하여 델타를 확인합니다.
- 점수가 회귀된 경우: 계속 진행하기 전에 수정하세요. 점수가 떨어졌으면 완료로 선언하지 마세요.
모든 커밋 전: `pre_commit_code_health_safeguard`를 실행합니다.
PR 전: `analyze_change_set`을 실행합니다.
예제: 안티패턴 vs 올바른 루프
# 잘못된 예: 먼저 편집하고 나중에 확인
[code_health_review 없이 대규모 리팩토링]
# 잘못된 예: 점수 하락 무시
"테스트 통과" → Code Health가 감소했지만 작업 완료 처리
# 잘못된 예: 빨간 점수 파일(5 미만)에서 광범위 리팩토링
모듈 전체를 우회하여 정리
# 올바른 예: 검토 → 작은 변경 → 점수 → 커밋 보호 → analyze_change_set
ECC와의 페어링
| ECC 스킬 / 흐름 | Code Health MCP 역할 |
|---|---|
coding-standards | 스타일/명명; Code Health = 구조/복잡도 |
plankton-code-quality | 작성 시 린트/포맷; Code Health = 편집 전후 구조적 게이트 |
verification-loop / /quality-gate | "완료" 전 구조적 회귀 검사 추가 |
security-review | 보안 vs 유지보수성 — 관련 있을 때 둘 다 사용 |
tdd-workflow | 테스트 통과 ≠ 건강한 설계 — 리팩토링 후 점수 확인 |
컨텍스트 팁: ECC는 MCP 수를 낮게 유지할 것을 권장합니다. 실질적인 편집을 할 때 codescene을 활성화하고 필요하지 않을 때는 비활성화하세요.
관련 스킬
coding-standards— 기본 규칙plankton-code-quality— 작성 시 린트/포맷 훅verification-loop— 빌드/테스트/린트 게이트tdd-workflow— 테스트 우선 개발security-review— 보안 체크리스트documentation-lookup— Context7을 통한 라이브러리 문서 (직교)