Skill: Research

Mô tả

Skill này giúp tìm kiếm và phân tích repo mẫu trên GitHub trước khi triển khai. Thay vì "nghĩ từ đầu", chúng ta học hỏi từ những gì đã có, tiết kiệm thời gian và tránh lỗi phổ biến.

Khi nào sử dụng

• User đưa yêu cầu nhưng chưa rõ cách làm nhanh nhất
• Cần tìm patterns, architectures đã proven
• Muốn so sánh các approaches khác nhau
• Cần tìm libraries/tools phù hợp

Workflow

Phase 1: Parse Requirements

1. Đọc

   intake.md

   để hiểu context
2. Extract keywords cho search
3. Xác định tech stack constraints

Phase 2: GitHub Search

1. Tạo search queries thông minh
2. Tìm repos phù hợp (stars, recent activity, license)
3. Filter theo language/tech stack
4. Rank theo relevance

Phase 3: Deep Analysis

1. Phân tích cấu trúc thư mục của top repos
2. Xác định patterns được dùng
3. Tìm hiểu technologies và dependencies
4. Ghi nhận anti-patterns cần tránh

Phase 4: Summarize

1. Tổng hợp shortlist các repos hay nhất
2. Recommend architecture/patterns
3. Liệt kê lessons learned
4. Xuất output chuẩn

Output Format

File:

output/research/shortlist.json

{
  "query": "original search context",
  "timestamp": "2024-01-22T00:00:00Z",
  "intake_source": "output/intake/intake.md",
  "repos": [
    {
      "rank": 1,
      "name": "owner/repo-name",
      "url": "https://github.com/owner/repo-name",
      "stars": 5000,
      "forks": 500,
      "last_updated": "2024-01-15",
      "description": "Short description from GitHub",
      "language": "TypeScript",
      "license": "MIT",
      "relevance_score": 0.95,
      "technologies": ["React", "Next.js", "Prisma"],
      "patterns_found": [
        "monorepo with turborepo",
        "feature-based folder structure",
        "server components"
      ],
      "strengths": [
        "Well documented",
        "Active maintenance",
        "Good test coverage"
      ],
      "weaknesses": [
        "Complex setup",
        "Heavy dependencies"
      ],
      "notes": "Good example for enterprise-scale apps"
    }
  ],
  "summary": {
    "total_repos_analyzed": 50,
    "shortlisted": 5,
    "recommended_stack": {
      "frontend": "Next.js with App Router",
      "backend": "tRPC or Next.js API Routes",
      "database": "PostgreSQL with Prisma",
      "deployment": "Vercel"
    }
  }
}

File:

output/research/patterns.md

# Research Patterns Report

## Context
- **Project**: [from intake]
- **Search Date**: [timestamp]
- **Repos Analyzed**: [count]

---

## Recommended Architecture

### Pattern: [Name]
- **Source**: [repo link]
- **Why it fits**: [reasoning]
- **Implementation notes**: [how to apply]

### Folder Structure

src/ ├── app/ # Routes (Next.js App Router) ├── components/ # Reusable UI ├── lib/ # Utilities ├── services/ # Business logic └── types/ # TypeScript types

---

## Technology Recommendations

### Frontend
| Option | Pros | Cons | Recommended? |
|--------|------|------|--------------|
| Next.js | SSR, App Router, Vercel | Learning curve | Yes |
| Vite + React | Fast dev, simple | No SSR | For SPAs |

### Backend
| Option | Pros | Cons | Recommended? |
|--------|------|------|--------------|
| tRPC | Type-safe, fast | Next.js specific | Yes |
| Express | Flexible | More setup | No |

### Database
| Option | Pros | Cons | Recommended? |
|--------|------|------|--------------|
| Prisma + PostgreSQL | Type-safe ORM | Schema migrations | Yes |
| Drizzle | Lighter | Newer | Alternative |

---

## Code Patterns

### 1. [Pattern Name]
**Source**: [repo]
**Usage**: [when to use]

```typescript
// Example code from repo

2. [Pattern Name]

...

---

Anti-patterns to Avoid

1. [Anti-pattern]: [why it's bad, found in repo X]
2. [Anti-pattern]: [why it's bad]

---

Dependencies Worth Noting

Package	Purpose	Stars	License
package-name	Description	10k	MIT

---

Next Steps

1. Clone [recommended repo] as reference
2. Adapt [pattern] for our use case
3. Create specs based on this research

---

Generated by Research Skill | Based on [X] repos

## Search Strategies

### 1. Keyword-based Search

Basic search

language:typescript stars:>1000 "nextjs dashboard"

With topic filters

topic:react topic:typescript stars:>500

Recent and maintained

pushed:>2024-01-01 stars:>100 "auth"

### 2. Awesome Lists
- Tìm `awesome-*` lists liên quan đến tech stack
- Đây là curated lists với quality repos

### 3. GitHub Topics
- Browse topics: `github.com/topics/[topic]`
- Filter by language và stars

### 4. Similar Projects
- Dùng GitHub's "Used by" để tìm projects dùng cùng dependencies
- Check "Insights > Dependency graph"

## Scoring Criteria

| Criterion | Weight | Description |
|-----------|--------|-------------|
| **Stars** | 20% | Popularity indicator |
| **Recent Activity** | 25% | Maintained in last 6 months |
| **Documentation** | 20% | README, docs folder, examples |
| **Code Quality** | 20% | Structure, types, tests |
| **Relevance** | 15% | Match với requirements |

### Relevance Score Formula

score = (stars_norm * 0.2) + (activity_norm * 0.25) + (docs_score * 0.2) + (quality_score * 0.2) + (keyword_match * 0.15)

## Integration với Pipeline

### Input từ Intake
```javascript
// Đọc intake để extract keywords
const intake = readFile('output/intake/intake.md');
const keywords = extractKeywords(intake);
// => ['dashboard', 'authentication', 'react', 'typescript']

Output cho Spec-Kit

// Research cung cấp context cho specs
const patterns = readFile('output/research/patterns.md');
const shortlist = readFile('output/research/shortlist.json');
// => Dùng để tạo feature specs có grounding

Lệnh thực thi

# Search GitHub với keywords từ intake
node ".agent/skills/research/scripts/search-github.js"

# Phân tích một repo cụ thể
node ".agent/skills/research/scripts/analyze-repo.js" --repo owner/repo-name

# Generate full research report
node ".agent/skills/research/scripts/generate-report.js"

# Quick search với custom query
node ".agent/skills/research/scripts/search-github.js" --query "nextjs dashboard template"

Quy tắc cho AI Agent

DO

• Ưu tiên repos có tests và documentation
• Kiểm tra license trước khi recommend
• Ghi nhận cả pros và cons
• Update patterns.md với code examples

DON'T

• Đừng chỉ dựa vào stars (có thể outdated)
• Đừng copy code verbatim (chỉ learn patterns)
• Đừng bỏ qua security issues
• Đừng recommend repos không maintained

Environment Variables

# GitHub API Token (for higher rate limits)
GITHUB_TOKEN=ghp_xxxxx

# Optional: Custom API endpoint
GITHUB_API_URL=https://api.github.com

Rate Limiting

• Without token: 60 requests/hour
• With token: 5000 requests/hour
• Search API: 30 requests/minute

Always handle rate limits gracefully.

Tham khảo

• GitHub Search API
• GitHub Topics
• Awesome Lists