project-code-audit

Project Code Audit — Dead Code Detection & Safe Cleanup

When to Use

• User asks to "clean up", "remove unused files", or "audit the project"
• Before a refactoring push — first understand what's actually alive
• When you encounter files that "look unused" — verify systematically, don't guess
• When the project has no clear file ownership map
• Always check for AGENTS.md first — if one exists, read it before any audit step

Core Principle

Incremental + Verified. Never delete in bulk without testing. Change one thing, verify it works, move to the next. A big-bang cleanup is a big-bang breakage risk.

This user prefers incremental, test-each-step changes. Start with zero-risk deletions, test immediately, only then discuss medium-risk restructuring.

Step 0 — AGENTS.md (Project Navigation Map)

Before any audit, create or read AGENTS.md. This is the single file every AI agent reads first to understand the project.

What AGENTS.md contains

• Directory structure overview (depth 2-3)
• File naming convention (e.g. verb-noun.kebab-case.ts)
• "What to search for" table — maps user intent to file paths
• Current migration status (what's done, what's pending)

When to create one

• Project has no clear structure documentation
• You're about to do a multi-phase restructuring
• You found yourself searching for files by guessing names
• User complained about "not being able to find things"

AGENTS.md template

# Project Agent Map

> Read this first. Defines directory structure, file naming, and navigation.

## Directory structure
src/
├── domain-a/    (what this contains)
├── domain-b/    (what this contains)
├── api/         (thin route layer)
└── utils/       (shared utilities)

## File naming
- `verb-noun.kebab-case.ts` — search by verb first
- Example: `verify-payment.ts`, `get-daewoon.ts`, `oauth-naver.ts`

## Quick lookup
| Search term | File |
|---|---|
| login/oauth | src/user/oauth-*.ts |
| payment verify | src/payment/verify-payment.ts |

## Current status
- ✅ Phase completed
- 🚧 Phase in progress
- ⬜ Phase planned