Codebase Report

Codebase Report

Combine architecture analysis and codebase learning into a unified, structured report.

When to Use

• Onboarding a new developer (human or AI agent) to an unfamiliar codebase
• Auditing a codebase before making significant changes
• Preparing documentation for external contributors
• Evaluating a codebase for acquisition or integration

Report Structure

The report combines the architectural view from codebase-analyzer with the practical understanding from codebase-learner:

# Codebase Report: 

---

## Executive Summary

---

## Project Overview
- **Purpose**: What the project does in one sentence
- **Tech Stack**: Languages, frameworks, databases, build tools
- **Size**: File count, line count, test count, coverage percentage
- **Maturity**: Age, release frequency, active maintenance

---

## Architecture

### System Diagram

### Layer Map
- Presentation layer: what handles incoming requests
- Business logic: where the domain logic lives
- Data layer: storage, caching, external APIs
- Infrastructure: config, middleware, deployment

### Module Boundaries

### Dependency Graph

---

## Data Flow

### Key Feature Walkthroughs

### State Management

### Error Handling

---

## Coding Conventions

### Style Guide (Inferred from Code)
| Convention | Pattern | Example |
|---|---|---|
| Variable naming | | |
| File naming | | |
| Error handling | | |
| Test structure | | |
| Import ordering | | |

### Common Idioms

### Anti-Patterns Detected

---

## Structural Health

### Code Smells
| Issue | Severity | Location |
|---|---|---|
| | high/medium/low | |

### Technical Debt
- TODO/FIXME/HACK count and age distribution
- Duplicated code instances
- Untested files
- Deprecated dependencies

### Architectural Violations
| Violation | Impact | Recommendation |
|---|---|---|
| | | |

---

## Gotchas

| Gotcha | Impact | Workaround |
|---|---|---|
| Must run migration before first start | Crash on startup | `npm run db:migrate` |
| God file with side effects on import | Unpredictable behavior | Import specific functions only |

---

## Confidence Map

| Area | Confidence | Notes |
|---|---|---|
| | high/medium/low | |

---

## Recommended Study Path

1. Start with: 
2. Then: 
3. Then: 
4. Finally: 

---

## Open Questions

1. 
2. 

---

## Dependencies Health

| Package | Version | Last Updated | CVEs | Status |
|---|---|---|---|---|
| | | | | ✓/⚠/✗ |

---

## Appendix

### File Inventory

### Test Coverage Detail

### Git Activity

How to Generate

1. Run codebase-analyzer agent for architecture, data flow, dependency analysis
2. Run codebase-learner agent for pattern learning, gotcha hunting, confidence mapping
3. Combine both outputs into the unified report format above
4. Save to .workflow/codebase-report/report-.md
5. Highlight critical findings (security issues, architectural violations) for immediate attention

Integration with Multi-Agent Workflow

This skill is triggered as part of the multi-agent-git-workflow research wave:

[Repo Scanner] → maps surfaces
       ↓
[Codebase Analyzer] → architecture, data flow, patterns
       ↓
[Codebase Learner] → studies conventions, finds gotchas
       ↓
[Codebase Report] → unified report combining both analyses

The report is then used by the Micro-Task Decomposer to make informed task breakdowns that respect existing conventions and avoid known pitfalls.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: noah-sheldon
• Source: noah-sheldon/ai-dev-kit
• License: MIT
• Homepage: https://noahsheldon.dev

Install and usage instructions live in the source repository linked above.