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

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-project-profile	Project Profile (Repo Metadata Document)	10_Wiki/Topics	verified	self	Project Profile Repo Profile PROJECT.md	none	A	0.9	applied	project-profile onboarding documentation metadata engineering		2026-05-10	pending	language framework markdown 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)

---
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.

ADRs

See 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

# .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

# 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

# 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)

## 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 |