spec

Imported from kangkyunghyun/LinKHU (docs/spec/AGENTS.md). Install upstream with npx skills add kangkyunghyun/LinKHU --skill spec. Copyright stays with the author.

AGENTS.md

LinKHU 스펙 세트를 읽고 고칠 때 필요한 문서와 코드 위치, 작성 규칙, 점검 방법을 안내한다. 확장 프로그램, 랜딩, 데이터, 릴리스와 스토어 운영을 다룬다.

명세 본문과 설정값은 이 문서에 복사하지 않는다. 스펙이 기준이라는 원칙, 번호 층위, 주제별 원본, 문서와 코드가 어긋날 때의 처리는 README에 있다.

1. 문서의 역할과 읽는 순서

• 처음에는 1부터 5까지 차례로 읽어 배경, 요구사항, 설계, 계약을 확인한다. 6은 구현 규약, 7은 오류, 검증, 배포를 다룬다.
• 앞 번호의 결정이 뒤 번호의 기준이다. 구현에 맞추려고 앞 번호를 임의로 바꾸지 않는다.
• 7-3은 결번이다. 이유는 README의 번호 층위 절에 있다.

2. 작업별 참조

3. 명세와 코드의 대응

코드를 바꾸면 짝지어진 문서를 같은 PR에서 갱신한다. 문서 갱신을 후속 PR로 미루지 않는다. 숨김 파일을 뺀 src/ 전체가 확장 패키지가 되며 dist/는 패키징 산출물이라 버전 관리 대상이 아니다.

4. 작성 규칙

스펙을 고치는 사람과 에이전트가 같은 기준으로 쓴다.

1. 무엇을 쓰나

2. 문서 형식

3. 문장

• '한다'체로 쓰고 주체, 조건, 동작을 분명히 쓴다. 한 문장에 내용 하나만 담는다.
• em dash, 원문자, 구획선을 쓰지 않는다. 본문의 가운뎃점은 쉼표나 와/과로 바꾼다. 카테고리 이름 같은 고유명사와 식별자는 원문 그대로 둔다.
• "이를", "이 값은" 같은 대명사 대신 가리키는 이름을 쓴다.
• "정본", "SSOT", "단일 진실 공급원"은 "원본"으로, "와이어링", "배선"은 "연결"로, "뜻"은 "의미"로 쓴다. "박다", "담보하다", "동봉하다", "수렴하다", "승격하다"는 "넣다", "보장하다", "함께 싣다", "맞춰진다", "옮기다"로 바꾼다.

5. 명령

스펙은 명령 대신 아래 "스펙에서 부르는 이름"을 쓴다.

1. 태그 push

git switch main
git pull --ff-only
VERSION=$(node -p "require('./src/manifest.json').version")
git tag "v$VERSION"
git push origin "v$VERSION"

2. Chrome 제출 실행

gh workflow run publish-chrome.yml --ref main \
  -f version={version} -f confirm_publish=publish-chrome

3. 공개 폼 점검

7-2-5의 표와 출력을 대조한다.

FORM=https://docs.google.com/forms/d/e/<폼 ID>/viewform
curl -sL "$FORM" -o /tmp/form.html

python3 - /tmp/form.html <<'PYEOF'
import re, sys, json
html = open(sys.argv[1], encoding="utf-8").read()
data = json.loads(re.search(r'FB_PUBLIC_LOAD_DATA_ = (.*?);</script>', html, re.S).group(1))
for question in data[1][1]:
    for entry in (question[4] or []):
        print(f'"{question[1]}"  entry.{entry[0]}  필수={"O" if entry[2] else "X"}')
PYEOF

6. 점검

스펙을 고친 PR은 아래를 돌린 뒤 올린다. 검색 결과는 문맥으로 판단할 후보이므로 일괄 삭제하지 않는다.

cd docs/spec

# 미래와 이력 문장
grep -nE '미정|추후|나중에|향후|예정|그때|이전에는|이전 스펙|정정|선행 작업|[0-9]{4}-[0-9]{2}-[0-9]{2} 기준' [1-7]*.md

# 책임 전가와 지양 표현, em dash
grep -nE '따른다|에서 다룬다|정본|SSOT|단일 진실|와이어링|뜻' [1-7]*.md
grep -n '—' *.md

# 링크와 앵커
python3 - <<'PY'
import re, pathlib
def slug(t):
    t = re.sub(r'[^\w\s-]', '', t.strip().lower())
    return re.sub(r'\s', '-', t)
heads = {p.name: {slug(h) for h in re.findall(r'^#+ (.+)$', p.read_text(), re.M)} for p in pathlib.Path('.').glob('*.md')}
for p in pathlib.Path('.').glob('*.md'):
    for target, anchor in re.findall(r'\]\(([\w.-]+\.md)?#([^)]+)\)', p.read_text()):
        name = target or p.name
        if name in heads and anchor not in heads[name]:
            print(f'{p.name}: {name}#{anchor}')
PY

# Mermaid 렌더
python3 - <<'PY'
import re, subprocess, pathlib
for p in sorted(pathlib.Path('.').glob('*.md')):
    for i, block in enumerate(re.findall(r'```mermaid\n(.*?)```', p.read_text(), re.S)):
        src = pathlib.Path(f'/tmp/{p.stem}-{i}.mmd'); src.write_text(block)
        r = subprocess.run(['npx', '-y', '@mermaid-js/mermaid-cli', '-i', str(src), '-o', f'/tmp/{p.stem}-{i}.svg'], capture_output=True)
        print(p.name, i, 'OK' if r.returncode == 0 else r.stderr.decode()[-200:])
PY

cd ../..
git diff --check
npm test