コードベースアセスメント は何をしますか？
あなたはレビュアーです。このスキルはコードベースからクライアントに提出可能なレポートへと導きます。
出力は 1つの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 — コードを読む
実行順序で読んでください: エントリポイント → ミドルウェア → ルーター → ハンドラー → サービス → データアクセス。欠陥はレイヤー間のギャップに存在するため、ファイル単位の読み取りでは見落とされます。
カテゴリgrep以外にも、METHODOLOGY.md § 発見 のテクニック（兄弟比較、アイデンティティトレーシング、エラーパス上の制御から結果への追跡、境界インベントリ）を使用してください。これらはgrepでは見つけられないものを発見します。
読んだ内容はその都度記録してください。coverage に必要です。
ステップ 4 — 報告する前に反証する
すべての候補は METHODOLOGY.md の4ステップを通過します。ほとんどの候補はステップ2または3で消えます。
- 生き残ったものを、それぞれ
confidenceを付けて発見事項として報告してください。 - 消えたものを、それを除外したステップと共に
refutedCandidatesに記録してください。これは単なる埋め草ではありません。レビューが厳格であったことを示す証拠であり、レポートに含まれます。 - 何かが実際に存在するが、最初に主張したほど深刻ではない場合は、削除するのではなくダウングレードしてください。
すべての発見事項には、実際の file と、それを開いた場合は line を含む evidence が必要です。コードを指し示せない場合、それは発見事項ではありません — 代わりに suggestions に含めるべきかもしれません。
繰り返しのインスタンスは、2～3の代表的な参照と instances カウントを持つ1つの系統的な発見事項に統合してください。1つの系統的な発見事項は、8つの重複よりも優れています。
ステップ 5 — スコアリング
- ディメンション。 デフォルトの7つは
scoring/dimensions.mdにあります。セットは設定可能です。エンゲージメントが必要とする場合は1つを交換してください（例：「品質保証/テスト」）。ただし、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— 方法、サイズ（およびその数え方）、深読みした内容、grepスイープした内容、読まなかった内容、および注意事項。具体的に記述してください。これにより、発見事項が反証可能になります。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/ | 全員。アプリケーションごとに1レポート。役員向け資料と完全な技術的エビデンスの両方をカバー。 |
<slug>.assessment.json | <repoPath>/architecture-review/ | レポートと一緒にコピーが置かれ、リポジトリが記録全体を保持します。assessments/ が正規の場所です。 |
Review-dashboard.html | <repoPath>/architecture-review/ | このクライアントのアプリケーションのみをロールアップ。すべてのレポート生成時に自動生成されます。他のクライアントの情報は含まれません。 |
アプリケーションごとに1レポート。 アーキテクチャレビューは、意思決定者向けの評決、目的、エグゼクティブサマリー、スコアカードで始まり、その後エンジニア向けのシステムモデル、カバレッジ、エビデンス、ロードマップに続きます。
2つのオプション出力が存在します。--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人日です。システムの規模に対して数値が大幅に外れている場合は、何かがずれています。通常は重要度のインフレーションか、統合されていない重複です。