[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -1,131 +1,256 @@
|
||||
---
|
||||
id: wiki-2026-0508-codescene
|
||||
title: CodeScene
|
||||
title: CodeScene (Behavioral Code Analysis)
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: []
|
||||
aliases: [CodeScene, behavioral code analysis, hotspot detection, code health, technical debt analytics]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.92
|
||||
tags: [auto-wikified, technical-documentation]
|
||||
source_trust_level: B
|
||||
confidence_score: 0.85
|
||||
verification_status: applied
|
||||
tags: [code-quality, codescene, behavioral-analysis, hotspot, technical-debt, refactoring, git-history]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-08
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
tech_stack:
|
||||
language: unspecified
|
||||
framework: unspecified
|
||||
language: SaaS / on-prem
|
||||
framework: CodeScene
|
||||
---
|
||||
|
||||
# CodeScene
|
||||
|
||||
## 📌 Brief 대략적 요약
|
||||
CodeScene은 단순한 정적 파일 분석이 아닌, 버전 관리 데이터와 코드 품질 메트릭을 결합한 행동 기반 코드 분석(Behavioral Code Analysis)을 통해 시스템의 변화를 추적하는 AI 코드 리뷰 도구입니다 [1]. 주요 차별점은 코드 복잡성과 변경 빈도가 교차하는 지점을 분석하여 기술적 부채와 개발 마찰(friction)이 심한 핫스팟을 찾아내는 방법론에 있습니다 [1, 2]. 이를 통해 개발 팀은 대규모 프로젝트나 레거시 시스템에서 아키텍처 문제가 프로덕션 인시던트로 발현되기 전에 선제적인 리팩토링과 유지보수를 수행할 수 있습니다 [2, 3].
|
||||
## 매 한 줄
|
||||
> **"매 git history 의 mining 으로 매 hotspot 의 detect"**. 매 정적 분석 X — 매 churn × complexity 의 교차점. 매 refactor priority 의 data-driven. 매 modern 의 alternative: SonarQube + 매 custom git script, Code Climate, Sourcegraph.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
- **행동 기반 코드 분석 (Behavioral Code Analysis):** CodeScene은 전통적인 정적 코드 분석과 달리, 커밋 히스토리, 코드 작성자 패턴, 코드 변경 빈도(churn)를 조사하는 시간적(temporal) 분석을 활용하여 개발 팀이 실제로 시스템을 어떻게 변경해왔는지 분석합니다 [1, 2].
|
||||
- **핫스팟 탐지 (Hotspot Detection):** 코드의 복잡성과 코드 변경 빈도의 교차점을 식별하는 방법론입니다 [1]. 이를 통해 개발 마찰이 높은 영역을 찾아내고 기술적 부채에 대한 우선순위를 데이터 주도적으로 정할 수 있게 해줍니다 [4].
|
||||
- **코드 건강도 지표 (Code Health Metric):** 코드 품질이 비즈니스에 미치는 영향을 1에서 10까지의 척도로 측정합니다 [2]. 이 지표는 결함 위험성(defect risk), 배포 속도(delivery speed), 예측 가능성(predictability)과 연관되어 검증된 수치입니다 [2].
|
||||
- **예측 모델과 리팩토링 가이드:** 아키텍처의 문제가 프로덕션 인시던트로 나타나기 전에 선제적으로 식별할 수 있는 예측 모델을 구축하여, 대규모 레거시 시스템을 관리하는 엔지니어링 팀에게 마찰에 기반한 리팩토링 지침을 제공합니다 [2-4].
|
||||
- **품질 게이트 (Quality Gates) 모니터링:** 시스템 내에서 코드 건강도 점수가 6점 미만으로 떨어질 경우 경고 알림을 발생시키는 모니터링 시스템을 설정할 수 있습니다 [4].
|
||||
## 매 핵심
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
- **Git 히스토리 의존성:** CodeScene의 효과적인 예측 모델을 구축하기 위해서는 최소 6개월 이상의 Git 히스토리가 필요합니다 [4, 5]. 따라서 최근에 저장소를 마이그레이션했거나 신규 구축된 팀에는 적합하지 않습니다 [5].
|
||||
- **정적 관점의 사각지대:** 행동 기반(Behavioral) 분석에 주로 초점을 맞추기 때문에, 변화가 자주 일어나지 않는 코드에 숨겨져 있는 일반적인 정적 코드(Static code) 문제나 취약점은 놓칠 수 있는 단점이 있습니다 [5].
|
||||
- **도입 장벽:** 행동 기반 메트릭이라는 상대적으로 새로운 지표를 팀이 올바르게 해석하고 활용하기 위해서는 일정 수준의 학습 곡선(Learning curve)이 요구되며, 엔터프라이즈 가격이 공개되어 있지 않다는 도입 상의 제약이 있습니다 [5].
|
||||
### 매 차별점 (vs 매 SAST)
|
||||
- 매 정적 X — 매 behavioral.
|
||||
- 매 git history 의 6 month+ 필수.
|
||||
- 매 churn (변경 빈도) × 매 complexity 의 hotspot.
|
||||
- 매 author pattern.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
### Related Concepts
|
||||
### 매 핵심 metric
|
||||
|
||||
#### [분석 및 평가 방법론 (Analysis Methodology)]
|
||||
- [[Behavioral Code Analysis]]
|
||||
- 연결 이유: CodeScene을 다른 정적 분석 도구들과 구분 짓는 가장 핵심적인 분석 프레임워크입니다 [1, 4].
|
||||
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 정적인 코드 문맥을 넘어 버전 관리 데이터, 작성자 패턴 등 팀의 행동 양식이 어떻게 아키텍처 품질의 평가 기준이 될 수 있는지 파악할 수 있습니다 [1, 2].
|
||||
- [[Hotspot Detection]]
|
||||
- 연결 이유: CodeScene이 위험 영역을 식별하는 주요 수단입니다 [1, 4].
|
||||
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 단순히 복잡한 코드뿐만 아니라, 빈번하게 수정되는 코드가 왜 기술적 부채의 가장 시급한 대상이 되는지(마찰 비용)를 이해하게 됩니다 [1, 2].
|
||||
#### Code Health (1-10)
|
||||
- 매 defect risk + delivery speed + predictability 의 결합.
|
||||
- 매 6 미만 의 alert.
|
||||
|
||||
#### [보완적/대조적 기술 (Complementary/Contrasting Tech)]
|
||||
- [[Static Code Analysis]]
|
||||
- 연결 이유: CodeScene이 행동 기반 분석에 집중함으로써 놓칠 수 있는 부분을 보완하는 데 필요한 대조적 개념입니다 [1, 5].
|
||||
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 코드베이스를 종합적으로 파악하기 위해 동적/행동 이력 분석과 구문 기반 정적 분석을 어떻게 결합해야 하는지 한계를 명확히 인지할 수 있습니다 [5].
|
||||
- [[Git History]]
|
||||
- 연결 이유: CodeScene이 작동하기 위해 반드시 요구되는 원천 데이터입니다 [4, 5].
|
||||
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 버전 관리 기록이 단순한 변경 이력의 저장소를 넘어, 코드베이스에 내재된 문제를 식별하고 예측하는 컨텍스트 도구로 활용되는 원리를 이해할 수 있습니다 [1, 2].
|
||||
#### Hotspot
|
||||
- 매 churn × complexity.
|
||||
- 매 top 5% 의 매 maintenance burden 의 80%.
|
||||
|
||||
### Deeper Research Questions
|
||||
- CodeScene의 1~10점 척도인 Code Health 메트릭은 구체적으로 어떤 코드 복잡도 지표들을 기반으로 산출되며, 결함 발생 위험과 어떠한 통계적 상관관계를 지니는가?
|
||||
- 최소 6개월 이상의 Git 히스토리가 요구되는 제약 조건을 극복하기 위해, 신규 프로젝트 초기에 적용할 수 있는 보완적인 행동 분석 전략은 무엇인가?
|
||||
- 대규모 마이크로서비스 또는 모노레포 환경에서 모듈 간 의존성이 얽혀 있을 때, CodeScene의 핫스팟 탐지는 어떻게 시스템 전반에 걸친 아키텍처 부채를 매핑하는가?
|
||||
- 행동 기반 메트릭을 코드 품질 파악 도구를 넘어 개발자들의 성과나 작업 패턴을 평가하는 지표로 오용할 경우 발생할 수 있는 조직적 부작용(사이드 이펙트)은 무엇인가?
|
||||
- 정적 소스 코드 분석(SAST) 도구와 CodeScene을 하나의 CI/CD 파이프라인에 통합할 때, 도출되는 위협 보고서의 우선순위를 어떤 기준으로 병합하여 알림 피로도(Alert fatigue)를 줄일 수 있는가?
|
||||
#### Knowledge Map
|
||||
- 매 author 의 dominate.
|
||||
- 매 bus factor.
|
||||
|
||||
### Practical Application Contexts
|
||||
- **Implementation:** CodeScene Enterprise를 적용하여 Git 히스토리를 분석한 뒤, 특정 파일이나 모듈의 Code Health 점수가 6 미만으로 하락하면 즉각적으로 알림을 보내는 품질 게이트(Quality Gate)를 구성할 수 있습니다 [4].
|
||||
- **System Design:** 장기간 운영된 레거시 시스템을 리팩토링할 때, 개발 팀의 수정 마찰(friction)이 가장 빈번한 핫스팟을 우선적으로 식별하여 리팩토링 로드맵의 우선순위를 데이터 기반으로 설계할 수 있습니다 [2, 4].
|
||||
- **Operation / Maintenance:** 프로덕션 인시던트가 발생하기 이전에 코드 이탈(churn) 및 커밋 내역을 통해 잠재적 아키텍처 붕괴 지점을 선제적으로 탐지하여 기술적 부채를 통제하는 유지보수 지표로 활용합니다 [2].
|
||||
- **Learning Path:** 복잡한 코드베이스를 읽는 법을 학습할 때, 정적인 소스 코드를 읽는 것을 넘어 '시간의 흐름에 따른 코드 변경 패턴(Git 히스토리)'을 분석하여 시스템의 취약점을 파악하는 심화 학습 과정으로 연결할 수 있습니다 [1, 2].
|
||||
- **My Project Relevance:** 프로젝트 내에 도입된 지 6개월 이상 된 리포지토리가 있다면, 리뷰 과정에서 단순히 로직 검증뿐 아니라 '가장 고통받는(마찰이 심한) 코드'를 발굴해 내는 분석 도구로 파일럿 테스트를 고려해볼 수 있습니다 [4, 5].
|
||||
#### Coupling
|
||||
- 매 file 의 매 같이 변경 의 frequency.
|
||||
- 매 logical coupling.
|
||||
|
||||
### Adjacent Topics
|
||||
- [[Technical Debt Management]]
|
||||
- 확장 방향: 핫스팟 탐지 및 Code Health 지표를 바탕으로 조직 내 기술 부채의 상환(Refactoring) 주기를 어떻게 우선순위화하고 비즈니스 지표와 정렬할 것인지 연구합니다 [2-4].
|
||||
- [[Predictive Maintenance Models]]
|
||||
- 확장 방향: 행동 분석 및 커밋 히스토리를 통해 미래의 결함을 선제적으로 예측하는 머신러닝/예측 기반 소프트웨어 엔지니어링 모델 연구로 확장합니다 [2, 4].
|
||||
### 매 limitation
|
||||
- 매 ≥6 month git history 필요.
|
||||
- 매 stale code (no churn) 의 weak signal.
|
||||
- 매 enterprise pricing.
|
||||
- 매 learning curve.
|
||||
|
||||
---
|
||||
*Last updated: 2026-05-02*
|
||||
### 매 alternative
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
#### Open-source / DIY
|
||||
- 매 git log + complexity tool.
|
||||
- 매 lizard, scc.
|
||||
|
||||
> *(TODO: 한 문장으로 핵심 통찰을 작성. "X는 Y 조건에서 Z 효과를 낸다" 구조 권장.)*
|
||||
#### SaaS competitor
|
||||
- **SonarQube + history**.
|
||||
- **Code Climate Velocity**.
|
||||
- **Sourcegraph**.
|
||||
- **Pluralsight Flow**.
|
||||
- **LinearB / Axify** (DORA-focused).
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
### 매 응용
|
||||
1. **Refactor priority**: 매 hotspot 의 first.
|
||||
2. **Onboarding**: 매 high-churn area 의 explain.
|
||||
3. **Architecture review**: 매 coupling 의 inspect.
|
||||
4. **Risk forecast**: 매 incident-prone area.
|
||||
5. **Bus factor**: 매 lone owner area.
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
## 💻 패턴
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
### Hotspot detection (DIY)
|
||||
```python
|
||||
import subprocess
|
||||
from collections import Counter
|
||||
import lizard # 매 complexity
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
def hotspots(repo, since='6 months ago', top_n=20):
|
||||
# 매 1. churn (commit count per file)
|
||||
log = subprocess.check_output(
|
||||
f'git -C {repo} log --since="{since}" --name-only --pretty=format:',
|
||||
shell=True, text=True,
|
||||
)
|
||||
churn = Counter(f for f in log.strip().split('\n') if f and f.endswith(('.py', '.ts', '.js')))
|
||||
|
||||
# 매 2. complexity (cyclomatic)
|
||||
complexity = {}
|
||||
for path, count in churn.items():
|
||||
try:
|
||||
ll = lizard.analyze_file(f'{repo}/{path}')
|
||||
complexity[path] = sum(f.cyclomatic_complexity for f in ll.function_list)
|
||||
except: pass
|
||||
|
||||
# 매 3. hotspot = churn × complexity
|
||||
scored = [(f, churn[f] * complexity.get(f, 0)) for f in churn]
|
||||
return sorted(scored, key=lambda x: -x[1])[:top_n]
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### Knowledge map (bus factor)
|
||||
```python
|
||||
def knowledge_map(repo, since='1 year ago'):
|
||||
log = subprocess.check_output(
|
||||
f'git -C {repo} log --since="{since}" --pretty=format:%an --name-only',
|
||||
shell=True, text=True,
|
||||
)
|
||||
|
||||
file_authors = {} # 매 file → Counter(author → lines)
|
||||
current_author = None
|
||||
for line in log.split('\n'):
|
||||
if line and not line.endswith(('.py', '.ts', '.js')):
|
||||
current_author = line
|
||||
elif line:
|
||||
file_authors.setdefault(line, Counter())[current_author] += 1
|
||||
|
||||
# 매 bus factor: 매 1 author 의 80%+ 의 file
|
||||
risk_files = []
|
||||
for f, authors in file_authors.items():
|
||||
total = sum(authors.values())
|
||||
top = authors.most_common(1)[0]
|
||||
if top[1] / total > 0.8:
|
||||
risk_files.append((f, top[0], top[1] / total))
|
||||
|
||||
return risk_files
|
||||
```
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### Logical coupling (changed-together)
|
||||
```python
|
||||
def logical_coupling(repo, since='6 months ago'):
|
||||
log = subprocess.check_output(
|
||||
f'git -C {repo} log --since="{since}" --pretty=format:COMMIT --name-only',
|
||||
shell=True, text=True,
|
||||
)
|
||||
|
||||
commits = log.split('COMMIT')
|
||||
coupling = Counter()
|
||||
for c in commits:
|
||||
files = [l.strip() for l in c.split('\n') if l.strip().endswith(('.py', '.ts'))]
|
||||
for i, a in enumerate(files):
|
||||
for b in files[i+1:]:
|
||||
coupling[tuple(sorted([a, b]))] += 1
|
||||
|
||||
return sorted(coupling.items(), key=lambda x: -x[1])[:20]
|
||||
```
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### Code health score (proxy)
|
||||
```python
|
||||
def health_score(file_path):
|
||||
"""매 simple proxy of CodeScene-style."""
|
||||
score = 10
|
||||
|
||||
ll = lizard.analyze_file(file_path)
|
||||
avg_cc = np.mean([f.cyclomatic_complexity for f in ll.function_list])
|
||||
if avg_cc > 10: score -= 2
|
||||
if avg_cc > 20: score -= 2
|
||||
|
||||
line_count = ll.nloc
|
||||
if line_count > 500: score -= 1
|
||||
if line_count > 1000: score -= 2
|
||||
|
||||
longest_func = max((f.length for f in ll.function_list), default=0)
|
||||
if longest_func > 50: score -= 1
|
||||
if longest_func > 100: score -= 2
|
||||
|
||||
return max(1, score)
|
||||
```
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
### CI integration (CodeScene API)
|
||||
```yaml
|
||||
# .github/workflows/codescene.yml
|
||||
- name: CodeScene Delta Analysis
|
||||
uses: empear-analytics/codescene-pr-check@v1
|
||||
with:
|
||||
api-url: ${{ secrets.CODESCENE_API_URL }}
|
||||
api-user: ${{ secrets.CODESCENE_USER }}
|
||||
api-token: ${{ secrets.CODESCENE_TOKEN }}
|
||||
project-id: 'my-project'
|
||||
fail-on-decline: true # 매 health 의 drop 시 의 fail
|
||||
```
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
### Quality gate
|
||||
```python
|
||||
def quality_gate(pr_files):
|
||||
"""매 PR 의 health 의 6 미만 시 의 fail."""
|
||||
failures = []
|
||||
for f in pr_files:
|
||||
score = health_score(f)
|
||||
if score < 6:
|
||||
failures.append((f, score))
|
||||
|
||||
if failures:
|
||||
return f'Quality gate failed: {failures}'
|
||||
return 'OK'
|
||||
```
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
### Refactor priority dashboard
|
||||
```python
|
||||
def refactor_dashboard(repo):
|
||||
return {
|
||||
'hotspots': hotspots(repo)[:10],
|
||||
'bus_factor_risks': knowledge_map(repo),
|
||||
'high_coupling': logical_coupling(repo)[:5],
|
||||
'health_distribution': {
|
||||
'critical': count_files_below(repo, 4),
|
||||
'concerning': count_files_in_range(repo, 4, 6),
|
||||
'ok': count_files_above(repo, 6),
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 🤔 결정 기준
|
||||
| 상황 | Tool |
|
||||
|---|---|
|
||||
| Enterprise + budget | CodeScene SaaS |
|
||||
| OSS / DIY | git script + lizard + custom dashboard |
|
||||
| DORA + general | LinearB / Axify |
|
||||
| Code search + ownership | Sourcegraph |
|
||||
| Quality gate (PR) | SonarQube + custom |
|
||||
| Bus factor only | git blame + script |
|
||||
|
||||
**기본값**: 매 small / OSS = 매 DIY. 매 enterprise = CodeScene 또는 LinearB.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[Code-Quality]] · [[Refactoring]] · [[Engineering-Productivity]]
|
||||
- 변형: [[Behavioral-Code-Analysis]] · [[Hotspot-Detection]] · [[Code-Health]]
|
||||
- 응용: [[Bus-Factor]] · [[Logical-Coupling]] · [[Quality-Gate]]
|
||||
- Adjacent: [[Code_Smells]] · [[Quality_Code_Review_Modern]] · [[Axify]] · [[SonarQube]] · [[Architecture-Anti-Patterns]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: 매 refactor priority. 매 onboarding. 매 architecture review. 매 incident prevention.
|
||||
**언제 X**: 매 < 6 month repo. 매 stale codebase analysis.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **모든 hotspot 의 fix**: 매 priority 의 use.
|
||||
- **Static analysis 의 ignore**: 매 churn-less issue 의 miss.
|
||||
- **Git history 의 trust 100%**: 매 squash / rebase 의 noise.
|
||||
- **Bus factor 의 ignore**: 매 critical risk.
|
||||
- **No quality gate**: 매 silent decline.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (Adam Tornhill "Your Code as a Crime Scene", CodeScene docs).
|
||||
- 신뢰도 B.
|
||||
- Related: [[Code_Smells]] · [[Quality_Code_Review_Modern]] · [[Axify]] · [[Architecture-Anti-Patterns]] · [[Asset-Specific-Knowledge]].
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — behavioral analysis + hotspot + 매 DIY git script + CI integration |
|
||||
|
||||
Reference in New Issue
Block a user