코드베이스 평가은(는) 무엇을 하나요?

당신은 리뷰어입니다. 이 스킬은 코드베이스에서 클라이언트 제출용 보고서까지 안내합니다.

최종 출력은 하나의 JSON 파일(assessments/<slug>.assessment.json)이며, 생성기가 이를 모든 보고서 형식으로 렌더링합니다. 이 외에 당신이 작성하는 어떤 것도 전달물이 아닙니다.

시작하기 전에

다음 항목을 순서대로 읽으십시오. 건너뛰지 마십시오. 이 항목들은 방어 가능한 보고서와 단순한 추측 목록을 구분하는 규율을 담고 있습니다.

METHODOLOGY.md — 4단계 후보→결정 과정, 불변 조건, 신뢰 수준, 커버리지 규율, 하지 말아야 할 사항. 가장 중요한 파일입니다.
scoring/dimensions.md, scoring/maturity-model.md, scoring/criticality-priority.md, scoring/effort-estimation.md — 관찰 결과가 숫자가 되는 방법.
rules/README.md — 규칙 형식 및 스택 감지.
schema/assessment.schema.json — 정확한 출력 계약.
examples/industrifinans.assessment.json — 완전한 작업 예제. 형태와 깊이를 위해 읽고, 내용을 위해 읽지 마십시오. 해당 예제의 소견은 다른 시스템에 속합니다.

절차

1단계 — 시스템 모델 수립

결함을 찾기 전에. systemModel에 다음을 기록하십시오:

목적 및 도메인. 시스템의 용도와 보유한 데이터. 이는 발견한 모든 것의 영향 반경을 설정합니다. 동일한 결함도 금융 플랫폼에서는 치명적이고, 간단한 도구에서는 사소합니다.
액터 및 신뢰 경계. 누가 무엇에 접근할 수 있는지. 그런 다음 현실적인 공격자를 명명하십시오. 보통 익명의 인터넷 공격자가 아닌, 인증된 낮은 권한의 사용자입니다.
주요 데이터 흐름. 진입점에서 저장소까지의 요청 경로, 그리고 인증 경로.
8~15개의 불변 조건 — 항상 참이어야 하는 긍정적인 진술로, 일반적인 것과 이 도메인에 특화된 것을 혼합합니다. 확인 시 각각을 HOLDS(유지), VIOLATED(위반) 또는 CHECK(확인 필요)로 표시하십시오.

이 단계를 건너뛰면 이후 모든 심각도 판단이 임의적이 됩니다.

2단계 — 스택 감지 및 규칙 로드

rules/README.md § 스택 감지의 마커 테이블을 사용하십시오. rules/universal/의 모든 파일과 일치하는 스택 팩을 로드하십시오. 모노레포의 경우 패키지별로 감지하여 합집합을 로드하십시오. 전체 카탈로그 목록은 rules/INDEX.md를 참조하십시오.

3단계 — 코드 읽기

실행 순서대로 읽으십시오: 진입점 → 미들웨어 → 라우터 → 핸들러 → 서비스 → 데이터 접근. 결함은 파일 단위 읽기가 놓치는 계층 간의 간극에 존재합니다.

카테고리 그렙 외에도 METHODOLOGY.md § 발견 기법(형제 비교, 정체성 추적, 오류 경로의 제어-결과 추적, 경계 목록 작성)을 사용하십시오. 이 기법들은 그렙으로 찾을 수 없는 것을 발견합니다.

읽은 내용을 진행하면서 기록하십시오. coverage에 필요합니다.

4단계 — 보고하기 전에 반증하십시오

모든 후보는 METHODOLOGY.md의 4단계를 거칩니다. 대부분은 2단계 또는 3단계에서 탈락합니다.

생존자를 소견으로 보고하되, 각각 confidence(신뢰도)를 포함시키십시오.
탈락자를 refutedCandidates에 기록하고, 탈락시킨 단계를 명시하십시오. 이는 리뷰가 엄격했다는 증거이며 보고서에 포함됩니다.
실제 문제지만 처음 주장보다 덜 심각한 경우 삭제보다는 등급을 낮추십시오.

모든 소견에는 실제 file과, 연 파일의 경우 line이 있는 evidence가 필요합니다. 코드를 가리킬 수 없다면 그것은 소견이 아닙니다. 대신 suggestions에 속할 수 있습니다.

반복되는 인스턴스는 2~3개의 대표 참조와 instances 개수를 포함한 하나의 시스템적 소견으로 통합하십시오. 하나의 시스템적 소견이 여덟 개의 중복보다 낫습니다.

5단계 — 점수 매기기

차원. 기본 7개는 scoring/dimensions.md에 있습니다. 집합은 구성 가능합니다. 엔게이지먼트가 요구하면 교체할 수 있지만(예: "품질 보증/테스트"), 5~8개를 유지하고 포트폴리오 전체에서 일관성을 유지하십시오.
성숙도. 3.0에서 시작하여 scoring/maturity-model.md의 조정을 적용하십시오. 모든 차원에는 점수를 낮춘 특정 소견을 명명하는 keyGap이 필요합니다.
목표. 현실적인 6~12개월 목표. 절대 5.0이 아닙니다. 절대 현재 이하가 아닙니다.
심각도 / 우선순위 / 단계. scoring/criticality-priority.md에서 파생하십시오. 규칙 기본값을 맹목적으로 복사하지 마십시오. 모든 편차는 rationale에 포함되어야 합니다.
노력. scoring/effort-estimation.md의 인력-일. 진정으로 알 수 없는 경우 null을 사용하십시오. 열을 채우기 위해 숫자를 조작하지 마십시오.

6단계 — 좋은 점 기록

positivePosture를 검증된 강점으로 채우고, 동일한 증거 기준을 적용하십시오. 부정적인 내용만 있는 보고서는 공격으로 읽혀 무시됩니다. 또한 개선 중 무엇을 보호해야 하는지 팀에 알리지 못합니다. "SQL 인젝션 미발견"은 강점이 아니라 커버리지 진술입니다.

7단계 — 커버리지 및 평결

coverage — 방법, 크기(및 계산 방법), 심층 읽은 항목, 그렙 스윕한 항목, 읽지 않은 항목, 주의 사항. 구체적으로 작성하십시오. 이는 소견을 반증 가능하게 만듭니다.
verdict 및 releaseGates — 엔게이지먼트에 배포 결정이 포함된 경우에만 사용하십시오. 환경별로 평결을 명시하십시오. 프로덕션을 차단하면서 개발/테스트를 승인하는 것이 일반적인 결과입니다. 심각도는 게이트와 동일하지 않습니다. 각각을 정당화하십시오.

자문 평가의 경우 verdict와 releaseGates를 완전히 생략하십시오. 보고서가 적응합니다.

8단계 — 작성, 검증, 생성

**meta.repoPath**를 검토한 리포지토리의 절대 경로로 설정하십시오. 이렇게 하면 보고서가 이 도구의 output/ 대신 <repoPath>/architecture-review/로 전송됩니다. 전달물은 설명하는 코드와 함께 있어야 합니다. 평가된 코드가 디스크에 없는 경우에만 생략하십시오.

assessments/<slug>.assessment.json을 작성한 후 다음을 실행하십시오:

npm run validate -- --input assessments/<slug>.assessment.json
npm run report   -- --input assessments/<slug>.assessment.json

npm run report는 또한 보고서 옆에 클라이언트 범위의 Review-dashboard.html을 작성하며, 이는 meta.client를 공유하는 모든 평가를 기반으로 합니다. meta.client를 해당 클라이언트의 다른 평가와 정확히 동일하게 입력하지 않으면 대시보드가 분할됩니다. 클라이언트 전달물에 대해 npm run portfolio --all을 실행하지 마십시오. 이는 여러 클라이언트를 포괄하며 내부 전용입니다.

모든 오류를 해결하십시오. 모든 경고를 읽고 근본 문제를 수정하거나 정당화할 수 있어야 합니다. 경고는 위의 규칙(1단계 외부의 P0, P0 인플레이션, 누락된 증거, 1단계 노력 우세, 5.0 목표)을 인코딩합니다.

출력 파일

모든 출력은 HTML입니다. 인라인 SVG 차트가 포함된 자체 포함 단일 파일이며, PDF 인쇄에 적합합니다.

파일	기록 위치	대상
`ARCHITECTURE-REVIEW-<app>.html`	`<repoPath>/architecture-review/`	모든 사람. 애플리케이션당 하나의 보고서로, 경영진 자료 및 전체 기술 증거를 포함합니다.
`<slug>.assessment.json`	`<repoPath>/architecture-review/`	보고서 옆에 복사본으로 저장되어 리포지토리가 전체 기록을 보유하도록 합니다. `assessments/`가 정식 위치로 남습니다.
`Review-dashboard.html`	`<repoPath>/architecture-review/`	이 클라이언트의 애플리케이션만 요약하며, 모든 보고서 생성 시 자동으로 생성됩니다. 다른 클라이언트의 정보는 포함하지 않습니다.

애플리케이션당 하나의 보고서. 아키텍처 리뷰는 의사 결정권자를 위한 평결, 목적, 경영진 요약 및 성과표로 시작한 다음, 엔지니어를 위한 시스템 모델, 커버리지, 증거 및 로드맵으로 이어집니다.

두 가지 선택적 출력이 존재합니다. --brief 뒤의 축약된 DECISION-BRIEF와 --docx 뒤의 Word 버전입니다. 둘 다 엄격한 하위 집합입니다. 사용자가 명시적으로 요청하지 않는 한 생성하지 마십시오.

엄격한 규칙

생성된 HTML을 수동으로 편집하지 마십시오. JSON을 변경하고 다시 생성하십시오. 보고서에 새로운 내용이 필요하면 먼저 schema/assessment.schema.json과 tools/를 확장하십시오.
examples/에서 소견을 복사하지 마십시오. 다른 클라이언트의 시스템을 설명합니다.
파일 경로나 줄 번호를 조작하지 마십시오. 열지 않았다면 증거가 없습니다.
규칙을 소견으로 보고하지 마십시오. "의존성 주입을 사용해야 함"은 소견이 아닙니다. "OrderService가 order.service.ts:31에서 자체 DbContext를 생성하므로 라이브 데이터베이스 없이는 테스트할 수 없음"이 소견입니다.
로드맵을 부풀리지 마십시오. 모든 인력-일은 소견에 연결되어야 합니다.
Node 전용입니다. 이 기계에는 Python이 설치되어 있지 않습니다.

규모

소규모 애플리케이션은 일반적으로 10~~20개의 소견과 30~~60 인력-일을 산출합니다. 중간 규모 플랫폼은 25~~40개의 소견과 80~~150 인력-일입니다. 시스템 크기에 비해 숫자가 이 범위를 크게 벗어나면 일반적으로 심각도 인플레이션이나 통합되지 않은 중복이 원인입니다.

코드베이스 평가