ReddRadar
Agent skill
Repo Map SSOT
Single source of truth for repository structure and entry points, including key directories, domain boundaries, shared code, integrations, and build/deploy references
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/repo-map-ssot
SKILL.md
Repo Map SSOT
Overview
Single Source of Truth (SSOT) สำหรับ repository structure ที่ให้ AI และคนเข้าใจ codebase ได้ทันที รวม folder structure, key files, และ architectural decisions ในที่เดียว
Why This Matters
- Quick orientation: รู้ว่าอะไรอยู่ตรงไหนทันที
- AI efficiency: AI ไม่ต้อง explore ซ้ำทุกครั้ง
- Onboarding: คนใหม่เข้าใจ repo structure เร็ว
- Consistency: ทุกคนมี mental model เดียวกัน
Core Concepts
1. Structure Overview
- สรุป “โครงบนสุด” ของ repo ให้เห็นภาพใน 30 วินาที (src/tests/docs/scripts/config)
- ระบุว่าเป็น monorepo หรือ single service และ boundaries อยู่ตรงไหน
2. Key Directories
- เขียน “purpose” ของแต่ละโฟลเดอร์ใหญ่เป็น 1–2 บรรทัด (อะไรอยู่ในนั้น / อะไรไม่ควรอยู่)
- ใส่ ownership ถ้ามี (ทีม/owner) เพื่อช่วย routing PR/review
3. Entry Points
- ระบุไฟล์เริ่มต้น: server bootstrap, routes, DI/container, job runners, consumers
- ระบุ “happy path”: ถ้าจะตาม flow request เข้า service ต้องเริ่มอ่านที่ไหน
4. Configuration Files
- บอกที่อยู่ของ env/config และลำดับความสำคัญ (สอดคล้องกับ config conventions)
- list config files ที่ทำให้ deploy แตกต่าง (docker, k8s, terraform, workflows)
5. Domain Boundaries
- ระบุ domain modules และ dependency direction (domain ไม่ควรรู้ infra)
- ระบุ shared contracts/types และวิธี versioning/backward-compat
6. Shared Code
- รวม “จุดรวม” ของ shared libs และข้อห้าม (เช่น ห้าม import จาก app layer)
- อธิบาย pattern ของ barrel exports (ใช้/ไม่ใช้) เพื่อลด confusion
7. External Integrations
- list integrations สำคัญ (payment, auth, email, analytics) + config location + docs link
- ระบุ webhook/queues/topics ที่เกี่ยวข้อง (ถ้ามี)
8. Build & Deploy
- ระบุ scripts ที่ต้องรู้: build/test/lint/migrate/seed
- ระบุ pipeline/deploy target (GitHub Actions, k8s, ECS, serverless) และไฟล์ config ที่เกี่ยวข้อง
Quick Start
# Create/maintain `REPO.md` at repo root:
# - 30s overview (tree + key entry points)
# - Where configs live (env, secrets, deploy)
# - Domain boundaries + owners
# - Links to deeper docs (architecture, API, runbooks)
Production Checklist
- REPO.md exists at root
- All major directories documented
- Entry points clearly marked
- Domain boundaries defined
- Kept up-to-date (review quarterly)
- Links to detailed docs
Repo Map Template
# REPO.md - Repository Map
> Last updated: 2024-01-15 | Auto-generated: Yes
## Quick Overview
[Project name] - [One sentence description]
## Structure
```
├── src/ # Application source code
│ ├── api/ # HTTP/REST endpoints
│ ├── domain/ # Business logic, entities
│ ├── infrastructure/ # Database, external services
│ └── shared/ # Cross-cutting utilities
├── tests/ # Test files (mirrors src/)
├── docs/ # Documentation
├── scripts/ # Build, deploy, utility scripts
├── config/ # Environment configs
└── [key files at root]
```
## Entry Points
| File | Purpose |
|------|---------|
| `src/index.ts` | Application bootstrap |
| `src/api/routes.ts` | API route definitions |
| `package.json` | Dependencies, scripts |
## Key Directories
### `src/api/`
HTTP layer: routes, controllers, middleware
- Owner: @backend-team
- Related: OpenAPI spec at `docs/api.yaml`
### `src/domain/`
Business logic, domain models, services
- Owner: @domain-team
- Pattern: Domain-Driven Design
### `src/infrastructure/`
External integrations: DB, cache, queues, APIs
- Owner: @infra-team
## Configuration
| File | Purpose |
|------|---------|
| `.env.example` | Required environment variables |
| `config/default.ts` | Default configuration |
| `tsconfig.json` | TypeScript settings |
## External Dependencies
| System | Purpose | Config Location |
|--------|---------|-----------------|
| PostgreSQL | Primary database | `src/infrastructure/db/` |
| Redis | Caching, queues | `src/infrastructure/cache/` |
| Stripe | Payments | `src/infrastructure/stripe/` |
## Build & Deploy
- Build: `npm run build`
- Test: `npm test`
- Deploy: GitHub Actions → AWS ECS
## Quick Commands
```bash
npm run dev # Start dev server
npm run test # Run tests
npm run lint # Lint code
npm run build # Build for production
```
## Related Docs
- [Architecture](./docs/architecture.md)
- [API Reference](./docs/api.md)
- [Development Guide](./docs/development.md)
Anti-patterns
- No map: ต้อง explore ทุกครั้ง
- Outdated map: ไม่ตรงกับ reality
- Too detailed: เป็น full docs แทน overview
- Missing entry points: ไม่รู้จะเริ่มจากไหน
Auto-Generation
# Generate repo map from folder structure
find . -type d -name "node_modules" -prune -o -type f -print | \
grep -E '\.(ts|js|py|go)$' | \
tree --fromfile > REPO_STRUCTURE.txt
Integration Points
- IDE plugins (file tree)
- Documentation generators
- AI context loaders
- CI checks (verify map is current)
Further Reading
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?