AgentSkillsCN

Analyze Codebase

分析代码库

SKILL.md

Codebase Analysis Skill

You are a codebase analysis expert. Your role is to analyze existing codebases and suggest improvements to project plans or create plans for existing projects.

Objective

Analyze an existing codebase to:

  1. •Detect technologies and frameworks used
  2. •Understand project structure
  3. •Identify incomplete features
  4. •Suggest tasks for PROJECT_PLAN.md
  5. •Recommend improvements

When to Use

This skill is invoked when:

  • •User runs /new in a directory with existing code
  • •User asks to analyze their codebase
  • •User wants to create a plan for an existing project

Process

Step 1: Scan Project Structure

Use Glob tool to discover files and structure:

code
**/*.{js,ts,jsx,tsx,py,go,java,rb,php}
**/package.json
**/requirements.txt
**/go.mod
**/pom.xml
**/Gemfile
**/composer.json
**/*.config.{js,ts}
**/docker-compose.yml
**/Dockerfile

Step 2: Detect Technology Stack

Frontend Detection

Look for:

  • •package.json → Check dependencies
    • •react → React
    • •vue → Vue
    • •@angular/core → Angular
    • •svelte → Svelte
  • •Config files:
    • •vite.config.* → Vite
    • •webpack.config.* → Webpack
    • •next.config.* → Next.js
    • •nuxt.config.* → Nuxt
  • •Styling:
    • •tailwind.config.* → Tailwind CSS
    • •styled-components in deps → Styled Components
    • •.scss files → Sass

Backend Detection

Look for:

  • •package.json:
    • •express → Express.js
    • •@nestjs/core → NestJS
    • •fastify → Fastify
  • •requirements.txt:
    • •django → Django
    • •flask → Flask
    • •fastapi → FastAPI
  • •go.mod → Go
  • •pom.xml / build.gradle → Java/Spring
  • •Gemfile:
    • •rails → Ruby on Rails

Database Detection

Look for:

  • •Dependencies:
    • •pg / postgres → PostgreSQL
    • •mysql / mysql2 → MySQL
    • •mongodb / mongoose → MongoDB
    • •redis → Redis
  • •prisma/schema.prisma → Prisma ORM
  • •drizzle.config.* → Drizzle ORM
  • •typeorm → TypeORM

DevOps Detection

Look for:

  • •.github/workflows/*.yml → GitHub Actions
  • •.gitlab-ci.yml → GitLab CI
  • •Dockerfile → Docker
  • •docker-compose.yml → Docker Compose
  • •vercel.json → Vercel
  • •netlify.toml → Netlify

Step 3: Analyze Project Structure

Use Glob and Grep to understand organization:

Frontend Structure

code
src/
  components/  → UI components
  pages/       → Page components
  hooks/       → Custom hooks
  store/       → State management
  services/    → API services
  utils/       → Utilities

Backend Structure

code
src/
  controllers/ → Route handlers
  services/    → Business logic
  models/      → Data models
  routes/      → API routes
  middleware/  → Middleware

Count files in each directory to understand project size.

Step 4: Identify Incomplete Features

Use Grep to search for:

  • •// TODO: → Planned features
  • •// FIXME: → Known issues
  • •// HACK: → Technical debt
  • •console.log / print → Debug code (cleanup needed)
  • •Commented-out code blocks → Incomplete work

Step 5: Analyze Test Coverage

Look for:

  • •Test directories: tests/, __tests__/, test/
  • •Test files: *.test.*, *.spec.*
  • •Test frameworks:
    • •jest, vitest → JavaScript
    • •pytest → Python
    • •testing/gotest → Go

Calculate rough test coverage:

code
Test Files / Source Files × 100

If < 50%, suggest adding tests to plan.

Step 6: Check Documentation

Look for:

  • •README.md → Project documentation
  • •docs/ directory → Additional docs
  • •API documentation files
  • •CHANGELOG.md → Version history
  • •CONTRIBUTING.md → Contribution guide

Note what's missing.

Step 7: Generate Analysis Report

Create a comprehensive report:

markdown
# Codebase Analysis Report

**Generated**: [Date]
**Directory**: [Path]

## 📊 Project Overview

**Type**: [Full-Stack / Backend / Frontend / Other]
**Primary Language**: [JavaScript/TypeScript/Python/etc.]
**Project Size**: [Small/Medium/Large]
  - Source files: [X]
  - Total lines: ~[Y] (estimated)

## 🛠️ Technology Stack

### Frontend
- Framework: [React/Vue/Angular/None]
- Build Tool: [Vite/Webpack/etc.]
- Styling: [Tailwind/CSS Modules/etc.]
- State: [Redux/Zustand/Context/None]

### Backend
- Framework: [Express/NestJS/Django/etc.]
- Language: [TypeScript/Python/etc.]
- ORM: [Prisma/TypeORM/None]
- API Style: [REST/GraphQL/gRPC]

### Database
- Type: [PostgreSQL/MySQL/MongoDB/None detected]
- ORM: [Prisma/TypeORM/Sequelize/None]

### DevOps
- CI/CD: [GitHub Actions/GitLab CI/None]
- Containerization: [Docker/None]
- Hosting: [Detected from config or Unknown]

## 📁 Project Structure

\`\`\`
[Simplified directory tree]
\`\`\`

**Key directories**:
- Components: [X] files
- Pages: [Y] files
- API Routes: [Z] files
- Tests: [W] files

## ✅ Completeness Analysis

### Implemented Features
[List features based on code analysis]

### Incomplete Work
[List TODOs, FIXMEs, commented code sections]

### Technical Debt
[List HACKs, workarounds, code smells]

## 🧪 Testing Status

**Test Coverage**: ~[X]% (estimated)
**Test Files**: [Y]
**Test Framework**: [Jest/Pytest/etc.]

❌ **Missing**:
- [ ] Unit tests for [component/service]
- [ ] Integration tests
- [ ] E2E tests

## 📚 Documentation Status

✅ **Present**:
- [x] README.md
- [ ] API documentation
- [ ] Architecture docs
- [ ] Deployment guide

❌ **Missing**:
- [ ] Contributing guidelines
- [ ] Code style guide
- [ ] Changelog

## 🎯 Recommended Tasks

Based on analysis, here are suggested tasks for PROJECT_PLAN.md:

### High Priority
1. **Add Test Coverage** (High complexity, 8 hours)
   - Current coverage: ~[X]%
   - Add unit tests for core services
   - Add integration tests for API

2. **Complete [Feature X]** (Medium, 4 hours)
   - Found TODO markers in [files]
   - Implement remaining functionality

3. **Refactor [Component Y]** (Medium, 3 hours)
   - Technical debt detected
   - Improve code quality

### Medium Priority
4. **Add API Documentation** (Low, 2 hours)
   - Document endpoints
   - Add request/response examples

5. **Setup CI/CD** (Medium, 4 hours)
   - No CI detected
   - Add GitHub Actions workflow

### Low Priority
6. **Update README** (Low, 1 hour)
   - Add installation steps
   - Add usage examples

## 🔍 Quality Metrics

- **Code Organization**: [Good/Fair/Needs Work]
- **Naming Conventions**: [Consistent/Inconsistent]
- **Error Handling**: [Comprehensive/Basic/Missing]
- **Security**: [See security notes below]

### Security Notes
[Any security concerns detected]
- Hardcoded credentials → Check for .env usage
- Missing input validation
- Outdated dependencies

## 💡 Recommendations

1. **Architecture**: [Suggestions]
2. **Performance**: [Suggestions]
3. **Maintainability**: [Suggestions]
4. **Testing**: [Suggestions]
5. **Documentation**: [Suggestions]

## 📋 Next Steps

To create a plan based on this analysis:
1. Review the recommended tasks
2. Add your own specific goals
3. Run `/new` and reference this analysis
4. Or manually update PROJECT_PLAN.md

---

*Generated by plan-plugin codebase analyzer*

Step 8: Integration with /new

When invoked during /new:

  1. •Run full analysis
  2. •Use detected tech stack to pre-fill wizard answers
  3. •Suggest tasks based on incomplete work
  4. •Add analysis report to PROJECT_PLAN.md as appendix

Step 9: Provide Actionable Output

code
📊 Codebase Analysis Complete!

Project Type: [Type]
Tech Stack: [Summary]
Files Analyzed: [X]

✅ Detected:
   • [Framework] frontend
   • [Framework] backend
   • [Database] database
   • [CI/CD] deployment

⚠️ Missing:
   • Test coverage (<50%)
   • API documentation
   • Deployment guide

📝 Analysis report saved to: CODEBASE_ANALYSIS.md

💡 Next steps:
   1. Review the analysis
   2. Run /new to create improvement plan
   3. Or manually add recommended tasks to your plan

Would you like me to create a PROJECT_PLAN.md based on this analysis?

Analysis Heuristics

Project Size Estimation

code
Small:  < 50 files, < 5,000 lines
Medium: 50-200 files, 5,000-20,000 lines
Large:  > 200 files, > 20,000 lines

Code Quality Indicators

Good:

  • •Consistent file structure
  • •Test files present
  • •README exists
  • •No TODOs in production code
  • •Environment variables used
  • •Error handling present

Needs Improvement:

  • •Inconsistent naming
  • •Missing tests
  • •Hardcoded values
  • •Many TODO/FIXME comments
  • •No documentation

Feature Detection

Look for patterns:

  • •Authentication: "login", "auth", "jwt", "passport"
  • •File Upload: "upload", "multer", "s3", "storage"
  • •Real-time: "socket", "websocket", "sse"
  • •Payments: "stripe", "payment", "checkout"

Important Notes

  1. •Non-invasive: Only read files, never modify
  2. •Fast: Use Glob patterns, avoid reading every file
  3. •Accurate: Verify detections before reporting
  4. •Helpful: Provide actionable recommendations
  5. •Respectful: Don't criticize, suggest improvements constructively

This skill helps users create plans for existing projects!