AgentSkillsCN

Ax Health Check

Ax Health Check

SKILL.md

AX Health Check Skill (프로젝트 점검)

프로젝트의 전반적인 상태를 점검합니다. 의존성, 구조, 타입, 린트, 빌드, 버전 동기화를 체크합니다.

트리거

  • /ax:health-check 명령
  • "프로젝트 점검" 프롬프트

실행 흐름

code
1단계: 프로젝트 의존성 및 구조 확인
    ↓
2단계: 타입 체크 실행
    ↓
3단계: 린트 검사 실행
    ↓
4단계: 빌드 테스트
    ↓
5단계: 버전 동기화 확인
    ↓
6단계: 점검 결과 리포트

실행 단계

1단계: 프로젝트 의존성 및 구조 확인

Python 환경:

bash
# Python 버전 확인
python --version

# 가상환경 상태 확인
pip list --outdated 2>/dev/null | head -20

# pyproject.toml 의존성 확인
cat pyproject.toml | grep -A 50 "dependencies"

Node.js 환경:

bash
# Node.js 버전 확인
node --version

# pnpm 버전 확인
pnpm --version

# 의존성 상태 확인
pnpm outdated 2>/dev/null || echo "의존성 확인 완료"

프로젝트 구조 확인:

bash
# 핵심 디렉토리 존재 여부
ls -la backend/ app/ .claude/ tests/ docs/

2단계: 타입 체크 실행

Python (mypy):

bash
mypy backend/ --ignore-missing-imports --no-error-summary 2>&1 || true

TypeScript (tsc):

bash
pnpm type-check 2>&1 || echo "TypeScript 타입 체크 완료"

3단계: 린트 검사 실행

Python (ruff):

bash
ruff check backend/ --output-format=concise 2>&1 || true

TypeScript/JavaScript (ESLint):

bash
pnpm lint 2>&1 || echo "ESLint 검사 완료"

4단계: 빌드 테스트

Python 패키지 빌드:

bash
# 패키지 설치 가능 여부 확인 (dry-run)
pip install -e . --dry-run 2>&1 || echo "Python 빌드 확인 완료"

TypeScript 빌드:

bash
pnpm build 2>&1 || echo "TypeScript 빌드 완료"

5단계: 버전 동기화 확인

버전 정보가 일치하는지 확인합니다:

파일확인 항목
package.jsonversion 필드
pyproject.tomlversion 필드
CLAUDE.md헤더의 버전 정보
docs/INDEX.md버전 표기 (있는 경우)
bash
# 버전 추출 및 비교
echo "=== 버전 동기화 확인 ==="
echo "package.json: $(node -p "require('./package.json').version" 2>/dev/null || echo 'N/A')"
echo "pyproject.toml: $(grep -m1 'version = ' pyproject.toml | cut -d'"' -f2)"

# Git 태그 확인
echo "Latest Git tag: $(git describe --tags --abbrev=0 2>/dev/null || echo 'No tags')"

6단계: 점검 결과 리포트

모든 점검 결과를 요약하여 리포트합니다.

점검 항목 상세

의존성 점검

항목기준상태
Python 버전>=3.11확인
Node.js 버전>=20.0.0확인
pnpm 버전>=9.0.0확인
오래된 패키지10개 미만 권장확인

타입 체크 기준

언어도구기준
Pythonmypy에러 0개
TypeScripttsc에러 0개

린트 기준

언어도구기준
Pythonruff에러 0개, 경고 최소화
TypeScriptESLint에러 0개

빌드 기준

대상기준
Python 패키지설치 가능
TypeScript빌드 성공

버전 동기화 기준

항목기준
package.json ↔ pyproject.toml동일
문서 버전일치
Git 태그package.json과 일치

출력 예시

code
🔍 프로젝트 점검 시작...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 1. 프로젝트 의존성 및 구조 확인
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[Python 환경]
  Python: 3.11.5 ✅
  pip packages: 45개 설치됨
  오래된 패키지: 3개

[Node.js 환경]
  Node.js: v20.11.0 ✅
  pnpm: 9.15.4 ✅
  오래된 패키지: 2개

[프로젝트 구조]
  backend/          ✅ 존재
  app/              ✅ 존재
  .claude/          ✅ 존재
  tests/            ✅ 존재
  docs/             ✅ 존재

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔤 2. 타입 체크
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[mypy - Python]
  ✅ Success: no issues found in 42 source files

[tsc - TypeScript]
  ✅ 타입 에러 없음

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 3. 린트 검사
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[ruff - Python]
  ✅ All checks passed!
  0 errors, 0 warnings

[ESLint - TypeScript]
  ✅ All checks passed!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔨 4. 빌드 테스트
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[Python 패키지]
  ✅ 설치 가능 확인됨

[TypeScript 빌드]
  ✅ 빌드 성공

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔄 5. 버전 동기화 확인
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

package.json:     0.5.0
pyproject.toml:   0.5.0
Git 태그:         v0.5.0

✅ 모든 버전 동기화됨

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 점검 결과 요약
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| 항목 | 상태 | 비고 |
|------|------|------|
| 의존성/구조 | ✅ | 정상 |
| 타입 체크 | ✅ | 에러 0개 |
| 린트 검사 | ✅ | 에러 0개 |
| 빌드 테스트 | ✅ | 성공 |
| 버전 동기화 | ✅ | 일치 |

🎉 프로젝트 상태: 양호 (5/5 통과)

문제 발견 시 출력 예시

code
🔍 프로젝트 점검 시작...

...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔤 2. 타입 체크
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[mypy - Python]
  ❌ 에러 발견 (3개)

  backend/api/routes/inbox.py:45: error: Argument 1 to "create_signal"
  has incompatible type "str"; expected "SignalCreate"

  backend/agent_runtime/base.py:78: error: Missing return statement

  backend/integrations/confluence.py:112: error: "None" has no attribute "json"

...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔄 5. 버전 동기화 확인
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

package.json:     0.5.0
pyproject.toml:   0.5.0
Git 태그:         v0.4.1

⚠️ 버전 불일치 발견!
   Git 태그가 package.json과 일치하지 않습니다.

💡 해결: git tag -a v0.5.0 -m "v0.5.0 릴리스" && git push origin v0.5.0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 점검 결과 요약
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| 항목 | 상태 | 비고 |
|------|------|------|
| 의존성/구조 | ✅ | 정상 |
| 타입 체크 | ❌ | 에러 3개 |
| 린트 검사 | ✅ | 에러 0개 |
| 빌드 테스트 | ✅ | 성공 |
| 버전 동기화 | ⚠️ | Git 태그 불일치 |

⚠️ 프로젝트 상태: 점검 필요 (3/5 통과)

📋 권장 조치:
1. mypy 타입 에러 3개 수정
2. Git 태그 v0.5.0 생성 및 푸시

옵션

옵션설명기본값
--quick빠른 점검 (타입/린트만)false
--full전체 점검 (테스트 포함)false
--fix자동 수정 가능한 항목 수정false
--jsonJSON 형식으로 결과 출력false

사용법

code
/ax:health-check              # 기본 점검 (5개 항목)
/ax:health-check --quick      # 빠른 점검 (타입/린트만)
/ax:health-check --full       # 전체 점검 (테스트 포함)
/ax:health-check --fix        # 자동 수정 적용 (ruff --fix)

자동 수정 지원

--fix 옵션 사용 시 자동으로 수정 가능한 항목:

항목도구명령
Python 린트ruffruff check --fix backend/
Python 포맷ruffruff format backend/
TypeScript 린트ESLintpnpm lint --fix

에러 처리

에러메시지해결 방법
Python 미설치"Python을 찾을 수 없습니다"Python 3.11+ 설치
Node.js 미설치"Node.js를 찾을 수 없습니다"Node.js 20+ 설치
의존성 미설치"패키지가 설치되지 않았습니다"pip install -e .[dev] 또는 pnpm install
빌드 실패"빌드 중 오류 발생"에러 메시지 확인 후 수정

관련 스킬

  • /ax:wrap-up - 작업 정리 및 커밋
  • /ax:confluence - Confluence 동기화

관련 문서