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가 다운되었을 때 게이팅을 위해 lint/테스트/확인 루프를 우선 사용하세요. 서버가 연결되면 검사를 다시 활성화하세요.
사용 시기
- 사용자가 코드 품질 검토, 파일 리팩터링, 또는 AI 변경으로 인한 유지보수성 저하 확인을 요청할 때
- 핫스팟, 레거시 모듈 또는 익숙하지 않은 파일을 편집하기 전
- 유지보수성 안전 장치가 필요할 때 커밋 또는 풀 리퀘스트 전
- 대규모 에이전트 작성 diff 후: Code Health가 퇴보하지 않았는지 확인
- 구조적 검사로
verification-loop,tdd-workflow또는/quality-gate와 함께 사용 (테스트/lint를 대체하지 않음)
활성화 시기
위의 사용 시기와 동일한 트리거입니다. 이 헤딩은 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 | 작성 시 lint/포맷; Code Health = 편집 전/후 구조 게이트 |
verification-loop / /quality-gate | "완료" 전에 구조적 회귀 검사 추가 |
security-review | 보안 vs 유지보수성 — 관련 있을 때 둘 다 사용 |
tdd-workflow | 테스트 통과 ≠ 건강한 설계 — 리팩터링 후 점수 확인 |
컨텍스트 팁: ECC는 MCP 수를 적게 유지하는 것을 권장합니다. 실질적인 편집을 할 때 codescene을 활성화하고 필요하지 않을 때 비활성화하세요.
관련 스킬
coding-standards— 기본 규칙plankton-code-quality— 작성 시 lint/포맷 훅verification-loop— 빌드/테스트/lint 게이트tdd-workflow— 테스트 우선 개발security-review— 보안 체크리스트documentation-lookup— Context7을 통한 라이브러리 문서 (직교)