refactor(topics): 멀티 에이전트용 지식 재편 — _Common(공통 기본기) + Domain_* 구조
에이전트 8종(대화형/프로그래머 C·S/디자이너/설계자/기획자/QA/PD/PM)에게 [공통 기본 능력 + 롤별 Specialty] 2층으로 지식을 주입하기 위한 재분류. 문서 내용·포맷은 무수정, 폴더 이동만 (6,372개 문서 수 보존 확인). - Topic_Programming → Domain_Programming (내부 구조 보존) - Topic_Graphic → Domain_Design - Topic_Business → Domain_Product - Topic_General → Domain_General - _Common 신설: Math(구 Topic_Math_Specialty), Reasoning(구 General/From_Thinking & Reasoning), Reasoning_Creativity(구 General/From_창의성), Communication(Poetic_Blog_Writing + From_writing) - 타 도메인의 From_* 폴더는 유지 (출처 표기일 뿐, 이미 도메인에 맞게 분류된 문서) - 빈 폴더 정리 (memory/procedures) - 에이전트→폴더 매핑은 workspace의 .astra/agent-knowledge-map.json (9개 에이전트) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,209 @@
|
||||
---
|
||||
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 |
|
||||
Reference in New Issue
Block a user