2nd/10_Wiki/Topics/Other/project-profile.md

---
id: wiki-2026-0508-project-profile
title: Project Profile (Repo Metadata Document)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Project Profile, Repo Profile, PROJECT.md]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [project-profile, onboarding, documentation, metadata, engineering]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: markdown
  framework: github-readme-spec
---

# Project Profile (Repo Metadata Document)

## 매 한 줄
> **"매 single-page document that answers: what is this repo, who runs it, how do I run it, where is it deployed"**. 2026 modern engineering — replaces sprawling wiki tribal knowledge with a versioned, reviewable, machine-parseable PROJECT.md / project-profile.md at repo root, consumed by humans 와 LLM coding agents (Claude Code, Copilot Workspace) alike.

## 매 핵심

### 매 mandatory sections
- **Identity**: name, slug, owners (tech + product), Slack channel, on-call rotation.
- **Purpose**: 1-paragraph "why this repo exists" — business problem, not implementation.
- **Stack**: languages, frameworks, runtime versions, key dependencies.
- **Run locally**: prereqs + 3-5 commands max to bootstrap dev env.
- **Deploy**: target environments, deploy mechanism (CI workflow link), rollback procedure.

### 매 secondary sections
- **Architecture diagram**: mermaid / draw.io link.
- **Data flows**: what services this calls, who calls this.
- **SLOs**: latency / availability targets.
- **Runbooks**: links to incident-response docs.
- **ADR index**: link to `doc/adr/README.md`.

### 매 LLM agent consumption
- LLM coding agents (Claude Opus 4.7, GPT-5 Workspace) read PROJECT.md FIRST when entering a repo.
- Frontmatter machine-parseable — agents pull tech_stack, owners, conventions.
- Reduces hallucinated assumptions (wrong test runner, wrong deploy target, etc.).

### 매 응용
1. New-hire onboarding (day-1 read).
2. Incident response (on-call finds owner / runbook fast).
3. LLM agent context-priming (agent reads profile → executes commands correctly).
4. Cross-team integration (team A wants to consume team B's service — reads profile first).

## 💻 패턴

### Minimal profile (markdown)
```markdown
---
name: orders-service
slug: orders
owners:
  tech: alice@acme.com
  product: bob@acme.com
slack: "#orders-team"
oncall: pagerduty.com/services/orders
stack:
  language: go
  runtime: 1.23
  framework: chi
  db: postgres-16
---

# orders-service

## Purpose
Authoritative store for customer orders. Handles checkout, fulfillment events.

## Run locally
```bash
make dev
curl localhost:8080/healthz
```

## Deploy
Auto-deploy on merge to `main` via `.github/workflows/deploy.yml`.
Rollback: `gh workflow run rollback.yml -F sha=<prev>`.

## Architecture
See [docs/architecture.md](docs/architecture.md).

## ADRs
See [doc/adr/](doc/adr/).
```

### Frontmatter spec (YAML, agent-readable)
```yaml
---
name: <kebab-case>
slug: <short>
version: 1
owners:
  tech: <email>
  product: <email>
  security: <email>
slack: "#channel"
oncall: <pagerduty-url>
repo: github.com/acme/orders-service
stack:
  language: <go|rust|python|ts>
  runtime: <version>
  framework: <name>
  db: <postgres-16|dynamo|...>
deploy:
  prod: <url>
  staging: <url>
  ci: .github/workflows/deploy.yml
slo:
  latency_p99_ms: 250
  availability: 99.9
---
```

### CI: profile schema validation
```yaml
# .github/workflows/profile-lint.yml
name: profile-lint
on: [pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install pyyaml jsonschema
      - run: python scripts/lint_profile.py PROJECT.md
```

```python
# scripts/lint_profile.py
import sys, yaml, jsonschema
schema = yaml.safe_load(open("schemas/project-profile.schema.yaml"))
text = open(sys.argv[1]).read()
fm = yaml.safe_load(text.split("---")[1])
jsonschema.validate(fm, schema)
print("ok")
```

### Org-wide profile aggregator
```python
# tools/aggregate_profiles.py
import requests, yaml, pathlib
ORG = "acme"
gh = requests.Session()
repos = gh.get(f"https://api.github.com/orgs/{ORG}/repos").json()
out = []
for r in repos:
    raw = gh.get(f"https://raw.githubusercontent.com/{ORG}/{r['name']}/main/PROJECT.md")
    if raw.status_code == 200 and "---" in raw.text:
        out.append(yaml.safe_load(raw.text.split("---")[1]))
pathlib.Path("catalog.yaml").write_text(yaml.dump(out))
```

### Mermaid embed (architecture)
```markdown
## Architecture
```mermaid
flowchart LR
  client --> gateway
  gateway --> orders[orders-service]
  orders --> postgres[(postgres)]
  orders --> kafka[(kafka)]
  kafka --> fulfillment
```
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Solo repo | Skip — README is enough |
| Service in team org | Mandatory PROJECT.md w/ frontmatter |
| Regulated org (SOC2, FDA) | Profile + ADR index + SLO doc |
| Multi-team monorepo | One profile per service dir |
| LLM-agent-heavy workflow | Frontmatter strict-schema validated in CI |

**기본값**: PROJECT.md at repo root, YAML frontmatter, CI lint, kept under 200 lines.

## 🔗 Graph
- 부모: [[Codebase_Onboarding]] · [[소프트웨어 설계 원칙 및 디자인 패턴|Engineering_Principles]]
- 변형: [[CODEOWNERS]]
- 응용: [[decisions]]
- Adjacent: [[Pull_Request_and_Issue_Tracking]] · [[GIT_PROTOCOL]]

## 🤖 LLM 활용
**언제**: Repo has > 1 contributor, repo is consumed by LLM coding agents, repo deploys to production.
**언제 X**: Throwaway scratch repo, single-script gist, ephemeral demo.

## ❌ 안티패턴
- **Stale profile**: Owner left 6 months ago, still listed — periodic CODEOWNERS sync needed.
- **Profile-as-novel**: 800-line PROJECT.md — split into ARCHITECTURE.md / RUNBOOK.md.
- **No frontmatter**: Free-form prose only — LLM agents can't reliably extract.
- **Docs-only, no CI lint**: Schema drift goes undetected for months.

## 🧪 검증 / 중복
- Verified (Backstage Software Catalog spec; GitHub `.github/PROJECT.md` convention; Spotify Tech Radar; Anthropic Claude Code agent repo onboarding behavior 2026).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — full Project Profile spec + frontmatter schema + CI lint patterns |