[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -1,31 +1,209 @@
|
||||
# Project Profile
|
||||
---
|
||||
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 Name
|
||||
Topics
|
||||
# Project Profile (Repo Metadata Document)
|
||||
|
||||
## Description
|
||||
Auto-detected from the local project path in the conversation.
|
||||
## 매 한 줄
|
||||
> **"매 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.
|
||||
|
||||
## Project Root
|
||||
/Volumes/Data/project/Antigravity/Wiki/10_Wiki/Topics
|
||||
## 매 핵심
|
||||
|
||||
## Record Root
|
||||
/Volumes/Data/project/Antigravity/Wiki/10_Wiki/Topics/docs/records/Topics
|
||||
### 매 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.
|
||||
|
||||
## Core Purpose
|
||||
Capture project direction, architecture discussion, decisions, and development notes as Markdown.
|
||||
### 매 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`.
|
||||
|
||||
## Target Users
|
||||
- Project developer
|
||||
### 매 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.).
|
||||
|
||||
## Avoid Directions
|
||||
- Do not mix records across projects.
|
||||
### 매 응용
|
||||
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).
|
||||
|
||||
## Record Detail Level
|
||||
standard
|
||||
## 💻 패턴
|
||||
|
||||
## Created
|
||||
2026-05-03T12:15:13.617Z
|
||||
### 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
|
||||
---
|
||||
|
||||
## Updated
|
||||
2026-05-03T12:15:13.617Z
|
||||
# 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]] · [[Service-Catalog-Backstage]]
|
||||
- 응용: [[decisions]] · [[Codebase_Maps_&_Interactive_Tours]]
|
||||
- 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