seokang-sk 0.2.2 → 0.3.0

package/README.MD

@@ -50,6 +50,8 @@ sk setup --configure-notion
 
 - Notion 문서 기록이 `invalid_grant`, `unauthorized`, `forbidden` 같은 인증 오류로 실패하면 아래 명령으로 MCP 인증을 다시 연결한다.
 - `Tool ... not found`처럼 특정 Notion tool만 빠진 경우는 로그인 문제가 아닐 수 있으니, exact error를 남기고 남아 있는 Notion MCP tool로 우회 가능한지 먼저 확인한다.
+- `notion-query-data-sources` / `query_data_sources`는 더 이상 Notion 기록의 1차 탐색 경로로 두지 않는다.
+- local config에 data source id가 있으면 `fetch` / `create_pages` / `update_page`를 먼저 쓰고, lookup이 필요할 때만 `search -> fetch` 순서로 보완한다.
 
 ```bash
 codex mcp login notion
@@ -61,6 +63,11 @@ codex mcp login notion
 - `docs/sk-cli-guide.md`
 - `docs/sk-notion-workspace.md`
 
+자동화 기준 문서:
+
+- `docs/automations/server-log-check.md`
+- `docs/automations/daily-thread-retrospective.md`
+
 이 저장소는 SeoKang 개인 개발 워크플로를 Codex Skill과 공용 Codex 데스크톱 설정 원본으로 관리하기 위한 저장소다.
 
 기능 개발, 버그 수정, 리팩토링, 기획, 배포뿐 아니라 문서화와 Notion 기록까지 포함한 작업 방식을 정리한다.
@@ -85,6 +92,8 @@ codex mcp login notion
 |  |- config/              # ~/.codex/config.toml 공용 원본
 |  |- agents/              # ~/.codex/agents 공용 원본
 |  |- rules/               # ~/.codex/rules 공용 원본
+|- templates/
+|  |- agent/               # 프로젝트용 AGENT.MD bootstrap 템플릿
 |- scripts/                # 공용 설치 / 보조 스크립트
 ```
 
@@ -94,6 +103,7 @@ codex mcp login notion
 
 - skill 동작 변경: `skills/sk-*/SKILL.md`
 - 설치/런타임 설정 변경: `codex-config/**`, `scripts/**`
+- 프로젝트용 AGENT.MD 기본 틀 변경: `templates/agent/*.md`
 - 사용법/운영 가이드 변경: `docs/**`, `README.MD`
 
 ---
@@ -108,7 +118,8 @@ codex mcp login notion
 ## 실행 방식
 
 - `sk`는 별도 앱 UI가 아니라 CLI 명령으로만 동작한다.
-- `sk setup`이 sync하는 대상은 `~/.codex`이고, `sk init`은 현재 프로젝트의 `.sk/` 상태를 준비한다.
+- `sk setup`이 sync하는 대상은 `~/.codex`이고, `sk init`은 현재 프로젝트의 `.sk/` 상태를 준비한다. 필요하면 `--agent-md`로 프로젝트 루트 `AGENT.MD`도 함께 만든다.
+- 옵션과 예시는 `sk help`, `sk help <command>`, `<command> --help`로 바로 확인한다. 예: `sk help init`, `sk init --help`
 - OMX가 `omx setup`처럼 짧아 보이는 이유는 npm 전역 CLI로 설치되기 때문이다.
 - 지금 `sk`도 최초 1회만 `npm link`로 등록하면 이후에는 `sk setup`, `sk init`만 기억하면 된다.
 - 실행 전제:
@@ -284,7 +295,7 @@ sk search "reviewer"
 
 상태 디렉터리:
 
-- `sk init`은 현재 작업 디렉터리 아래 `.sk/`를 만든다.
+- `sk init`은 현재 작업 디렉터리 아래 `.sk/`를 만들고, `--agent-md`를 붙이면 프로젝트 루트 `AGENT.MD`도 함께 만든다.
 - `sk setup`은 관리용 저장소 `~/.agents/skills/.sk/`를 setup 상태/백업 기준 경로로 사용한다.
 - `.sk/setup-scope.json`: 마지막 init/setup 기록
 - `.sk/project-memory.json`: 다음 세션이 읽을 구조화 메모
@@ -374,7 +385,8 @@ LOCAL_JAR_PATH=./build/libs/km-admin-api.jar
   - `--dry-run`, `--verbose`, `--configure-notion`, `--skip-notion`을 지원한다.
 - `init`
   - 현재 프로젝트 루트의 `.sk/` 상태 파일을 준비한다.
-  - `--cwd <path>`, `--dry-run`, `--force`, `--verbose`를 지원한다.
+  - `--agent-md`를 붙이면 프로젝트 루트에 `AGENT.MD` 초안도 함께 만든다.
+  - `--cwd <path>`, `--agent-md`, `--dry-run`, `--force`, `--verbose`를 지원한다.
 - `check`
   - 현재 설치가 source와 일치하는지 확인한다.
   - Notion workspace 설정 파일 존재 여부와 필수 필드도 함께 확인한다.
@@ -407,6 +419,25 @@ LOCAL_JAR_PATH=./build/libs/km-admin-api.jar
 - `sk-feature`, `sk-bugfix`, `sk-db`는 shared subagent가 설치되어 있으면 사용자가 따로 지시하지 않아도 내부적으로 dispatch할 수 있도록 설계한다.
 - 기본 분석용 subagent는 `Notion MCP`와 `Playwright`를 직접 사용하지 않고, 이런 tool 작업은 메인 agent가 맡는다.
 
+## 프로젝트 AGENT.MD
+
+- `AGENT.MD`는 프로젝트별 고정 규칙 문서다.
+- `README`는 사람용 개요/설치 문서, `.sk/*`는 세션 메모, `AGENT.MD`는 agent가 먼저 읽어야 할 프로젝트 계약서로 분리해서 쓴다.
+- 성능 차이가 크지 않은 한 기본 초안은 한글로 생성하고, 명령어/식별자/경로만 원문을 유지한다.
+- 새 프로젝트에서 바로 만들려면 아래처럼 시작한다.
+
+```bash
+sk init --agent-md
+```
+
+- 다른 프로젝트를 미리 준비할 때는 아래처럼 쓴다.
+
+```bash
+sk init --cwd /path/to/project --agent-md
+```
+
+- 기본 템플릿 원본은 `templates/agent/base.md`, `templates/agent/frontend.md`, `templates/agent/backend.md`, `templates/agent/codex.md`다.
+
 ## 작성자
 
 SeoKang 작성

package/docs/sk-cli-guide.md

@@ -58,7 +58,8 @@ sk setup
 이 명령은 크게 2가지를 한다.
 
 - `sk setup`은 `~/.agents/skills`를 준비하고 `~/.codex`에 공용 설정을 반영한다.
-- `sk init`은 현재 프로젝트의 `.sk/`에 작업 상태와 메모를 준비한다.
+- `sk init`은 현재 프로젝트의 `.sk/`에 작업 상태와 메모를 준비한다. 필요하면 `--agent-md`로 프로젝트 루트 `AGENT.MD`도 함께 만든다.
+- 각 명령의 옵션과 예시는 `sk help`, `sk help <command>`, `<command> --help`로 바로 확인할 수 있다.
 
 즉, `sk`는 단순 설치 스크립트가 아니라 "설치 + 점검 + 상태관리"를 묶은 진입점이다.
 
@@ -283,6 +284,17 @@ sk init
 - `.sk/project-memory.json`
 - `.sk/notepad.md`
 
+프로젝트 루트 `AGENT.MD` 초안도 같이 만들고 싶으면 아래처럼 실행한다.
+
+```bash
+cd /path/to/project
+sk init --agent-md
+```
+
+이 경우 아래 파일까지 함께 준비된다.
+
+- `AGENT.MD`
+
 ## 5. 상황별로 어떻게 쓰면 되는가
 
 ### 상황 A. 새 PC 또는 새 세션에서 기본 셋업 반영
@@ -290,7 +302,7 @@ sk init
 ```bash
 sk setup
 cd /path/to/project
-sk init
+sk init --agent-md
 sk check
 sk status
 ```
@@ -300,11 +312,11 @@ sk status
 ### 상황 B. 다른 프로젝트의 `.sk`를 미리 만들고 싶다
 
 ```bash
-sk init --cwd /path/to/project
+sk init --cwd /path/to/project --agent-md
 sk status --cwd /path/to/project
 ```
 
-이 경우 해당 프로젝트 밑 `.sk/`만 준비한다.
+이 경우 해당 프로젝트 밑 `.sk/`와 `AGENT.MD` 초안을 함께 준비한다.
 
 ### 상황 C. 이전 작업 맥락을 다시 보고 싶다
 
@@ -319,7 +331,7 @@ sk search "reviewer"
 
 ## 6. `.sk/`는 무엇인가
 
-`sk init`을 실행하면 현재 작업 디렉터리 아래 `.sk/`를 만든다.
+`sk init`을 실행하면 현재 작업 디렉터리 아래 `.sk/`를 만들고, `--agent-md`를 붙이면 프로젝트 루트 `AGENT.MD`도 함께 만든다.
 
 `sk setup`은 설치/백업 기준 상태를 `~/.agents/skills/.sk/`에 둔다.
 
@@ -329,12 +341,16 @@ sk search "reviewer"
   다음 세션이 읽을 구조화 메모
 - `.sk/notepad.md`
   우선순위 메모와 작업 메모
+- `AGENT.MD`
+  프로젝트별 고정 규칙과 검증/운영 계약
 - `.sk/backups/setup/**`
   setup 중 덮어쓰기 전에 남긴 backup
 - `~/.codex/sk/notion/workspace.json`
   사용자별 Notion workspace 설정
 
 중요한 점은 `.sk/`가 "이 프로젝트에서 다음 세션이 바로 이어서 일하게 만드는 상태 폴더"라는 것이다. 그래서 프로젝트마다 별도로 두는 것이 맞다.
+`AGENT.MD`는 그 위에 있는 장기 규칙 문서라서, `README`와 `.sk` 사이의 빈 구간을 메우는 역할로 본다.
+성능 차이가 크지 않은 한 기본 초안은 한글로 생성하고, 명령어/식별자/경로만 원문을 유지한다.
 
 ## 7. 지금 당장 외울 것은 무엇인가
 
@@ -384,7 +400,7 @@ sk search "keyword"
 ## 10. 가장 짧은 요약
 
 - `sk setup` = 설치 + 공용 Codex 설정 반영 + check
-- `sk init` = 현재 프로젝트 `.sk` 준비
+- `sk init` = 현재 프로젝트 `.sk` 준비 (`--agent-md`면 `AGENT.MD`도 함께 생성)
 - `sk check` = 설치 결과 점검
 - `sk status` = 지금 상태 확인
 - `sk memory show`, `sk search` = 이전 맥락 복원

package/docs/sk-notion-workspace.md

@@ -58,6 +58,9 @@ codex mcp login notion
 - public skill 본문에 개인 Notion URL, DB id, collection id를 직접 적지 않는다.
 - Notion 작업 전에는 먼저 local config 파일 존재 여부와 `configured` 상태를 확인한다.
 - local config가 없거나 `configured=false`면 Notion 기록 시도를 생략하고 Markdown fallback을 기본 출력으로 사용한다.
-- `Tool ... not found`처럼 특정 Notion MCP tool만 빠진 경우는 Notion 전체 장애로 단정하지 않는다. local config의 data source id와 project/history 위치가 있으면 `fetch`/`search`/`create_pages`/`update_page` 같은 생존 tool로 먼저 우회 시도한다.
+- `notion-query-data-sources` / `query_data_sources`는 optional lookup tool로 취급한다. 기본 경로로 먼저 호출하지 않는다.
+- local config의 data source id나 target page id가 있으면 `fetch` / `create_pages` / `update_page`를 먼저 사용한다.
+- lookup이 추가로 필요할 때만 `search -> fetch -> create_pages/update_page` 순서로 진행한다.
+- `Tool ... not found`처럼 특정 Notion MCP tool만 빠진 경우는 Notion 전체 장애로 단정하지 않는다. 생존 tool로 우회 가능하면 그 경로를 먼저 사용하고, 같은 missing tool을 같은 턴에 반복 재시도하지 않는다.
 - fallback Markdown를 나중에 Notion으로 옮길 때는 `Projects > History`의 `Date`를 이관 완료 시점의 로컬 datetime으로 다시 저장하고, `date:Date:is_datetime=1`을 유지한 뒤에만 fallback 파일을 제거한다.
 - 사용자가 이후 Notion 기록도 원하면 그때 `sk setup --configure-notion`을 안내하고, Notion MCP 실패 여부와 구분해서 보고한다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seokang-sk",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "SeoKang Codex 공용 설정과 스킬을 설치하는 CLI",
   "license": "MIT",
   "homepage": "https://github.com/Seokang/seokang-codex-setting",
@@ -26,7 +26,8 @@
     "docs/sk-cli-guide.md",
     "docs/sk-setup-architecture.md",
     "docs/sk-notion-workspace.md",
-    "scripts/sk.mjs"
+    "scripts/sk.mjs",
+    "templates/agent"
   ],
   "publishConfig": {
     "access": "public"

package/scripts/sk.mjs

@@ -11,7 +11,7 @@ import {
   writeFile,
 } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import { fileURLToPath } from 'node:url';
 
@@ -22,10 +22,12 @@ const DEFAULT_SCOPE = 'user';
 const STATE_DIRNAME = '.sk';
 const BACKUP_SEGMENT = join('backups', 'setup');
 const SESSION_FILE_RE = /^rollout-.*\.jsonl$/;
+const AGENT_MD_FILE = 'AGENT.MD';
 const PROJECT_MEMORY_FILE = 'project-memory.json';
 const NOTEPAD_FILE = 'notepad.md';
 const NOTION_CONFIG_SEGMENTS = ['sk', 'notion'];
 const NOTION_CONFIG_FILE = 'workspace.json';
+const AGENT_TEMPLATE_SEGMENTS = ['templates', 'agent'];
 const GUIDE_RELATIVE_PATH = join('docs', 'sk-cli-guide.md');
 const DEFAULT_BOOTSTRAP_REPO = 'https://github.com/Seokang/seokang-codex-setting.git';
 const CANONICAL_SKILLS_SEGMENTS = ['.agents', 'skills'];
@@ -583,6 +585,14 @@ function notepadPath(cwd = process.cwd()) {
   return join(stateRoot(cwd), NOTEPAD_FILE);
 }
 
+function agentMdPath(cwd = process.cwd()) {
+  return join(cwd, AGENT_MD_FILE);
+}
+
+function agentTemplatePath(name) {
+  return join(REPO_ROOT, ...AGENT_TEMPLATE_SEGMENTS, name);
+}
+
 function notionConfigPathForHome(codexHomeDir) {
   return join(codexHomeDir, ...NOTION_CONFIG_SEGMENTS, NOTION_CONFIG_FILE);
 }
@@ -605,54 +615,220 @@ function setupBackupRoot(cwd = process.cwd()) {
   return join(stateRoot(cwd), BACKUP_SEGMENT, stamp);
 }
 
-function printUsage() {
+function formatOptionLines(options) {
+  if (options.length === 0) return ['  (옵션 없음)'];
+
+  const width = options.reduce((max, option) => Math.max(max, option.flag.length), 0);
+  return options.map((option) => `  ${option.flag.padEnd(width)}  ${option.description}`);
+}
+
+function generalHelpLines() {
   const guidePath = join(REPO_ROOT, GUIDE_RELATIVE_PATH);
-  console.log(
-    [
-      'sk - SeoKang Codex 설정 도우미',
-      '',
-      '✨ 빠른 시작',
-      '  1. "seokang-sk"를 전역 설치했다면 먼저 "sk setup"을 1회 실행합니다.',
-      '  2. 이 저장소 자체를 개발 중이면 대신 "npm link"를 1회 실행합니다.',
-      '  3. 프로젝트 루트로 이동해 "sk init"으로 .sk 상태를 준비합니다.',
-      '  4. "sk check"로 설치 상태를 점검합니다.',
-      '  5. "sk status"로 현재 프로젝트 .sk 상태와 최근 백업을 확인합니다.',
-      '',
-      '🧰 자주 쓰는 명령',
-      '  sk setup                ~/.agents/skills 준비 + ~/.codex 동기화 + check 실행',
-      '  sk init                 현재 프로젝트의 .sk 상태 파일 초기화',
-      '  sk check                설치 결과가 공용 원본과 같은지 점검',
-      '  sk status               현재 프로젝트 .sk 상태와 최근 백업 확인',
-      '  sk memory show          저장된 프로젝트 메모와 공용 메모 확인',
-      '  sk search "<query>"     로컬 Codex 세션 기록 검색',
-      '',
-      '📝 사용법',
-      '  sk setup [--dir <path>] [--cwd <path>] [--repo <url>] [--dry-run] [--verbose] [--configure-notion] [--configure-db-safe-read] [--track <name>] [--skip-notion]',
-      '  sk init [--cwd <path>] [--dry-run] [--force] [--verbose]',
-      '  sk check [--cwd <path>] [--json]',
-      '  sk status [--cwd <path>] [--json]',
-      '  sk memory show [--cwd <path>] [--json]',
-      '  sk memory init [--cwd <path>] [--force]',
-      '  sk memory add-note [--cwd <path>] --category <name> <content>',
-      '  sk memory add-directive [--cwd <path>] [--priority high|normal] [--context <text>] <content>',
-      '  sk search <query> [--cwd <path>] [--limit N] [--since 7d] [--project current] [--case-sensitive] [--json]',
+  const commands = [
+    { name: 'sk setup', description: '공용 원본을 ~/.codex에 동기화하고 check까지 실행' },
+    { name: 'sk init', description: '현재 프로젝트의 .sk 상태 파일 준비' },
+    { name: 'sk check', description: '설치 결과와 공용 원본의 차이 점검' },
+    { name: 'sk status', description: '현재 프로젝트 상태와 최근 백업 확인' },
+    { name: 'sk memory show', description: '저장된 프로젝트 메모와 메모장 확인' },
+    { name: 'sk search "<query>"', description: '로컬 Codex 세션 기록 검색' },
+  ];
+  const commandWidth = commands.reduce((max, entry) => Math.max(max, entry.name.length), 0);
+
+  return [
+    'sk - SeoKang Codex 설정 도우미',
+    '',
+    '✨ 빠른 시작',
+    '  1. "seokang-sk"를 전역 설치했다면 먼저 "sk setup"을 1회 실행합니다.',
+    '  2. 이 저장소 자체를 개발 중이면 대신 "npm link"를 1회 실행합니다.',
+    '  3. 프로젝트 루트에서 "sk init --agent-md"로 .sk와 AGENT.MD 초안을 함께 준비합니다.',
+    '  4. "sk check"로 설치 상태를 점검합니다.',
+    '  5. "sk status"로 현재 프로젝트 상태를 확인합니다.',
+    '',
+    '🧰 주요 명령',
+    ...commands.map((entry) => `  ${entry.name.padEnd(commandWidth)}  ${entry.description}`),
+    '',
+    '📝 상세 사용법',
+    '  sk help <command> 또는 sk <command> --help 로 명령어별 옵션과 예시를 확인합니다.',
+    '  예: sk help init',
+    '',
+    '💡 참고',
+    '  - 배포된 npm 패키지는 설치 진입점과 디스패처 역할만 합니다.',
+    `  - setup은 수정 가능한 원본 저장소를 ${canonicalRepoRoot()} 경로에 준비합니다.`,
+    '  - init은 현재 프로젝트 루트에 .sk 상태 파일을 만들고, --agent-md를 붙이면 AGENT.MD 초안도 함께 생성합니다.',
+    '  - 다른 프로젝트를 대상으로 하려면 cd 대신 init/status/memory에 --cwd <path>를 사용할 수 있습니다.',
+    '  - Notion 기록이 invalid_grant/unauthorized/forbidden 같은 인증 오류로 실패하면 "codex mcp login notion"으로 MCP 인증을 다시 연결하세요.',
+    `  - 자세한 가이드: ${guidePath}`,
+  ];
+}
+
+function commandHelpLines(command) {
+  const helpByCommand = {
+    setup: {
+      title: 'sk setup - 공용 Codex 설정 초기화',
+      usage: 'sk setup [--dir <path>] [--cwd <path>] [--repo <url>] [--dry-run] [--verbose] [--configure-notion] [--configure-db-safe-read] [--track <name>] [--skip-notion]',
+      summary: [
+        '설치 진입점과 동기화 명령입니다.',
+        '관리용 skills 저장소를 준비하고, config / rules / shared agents를 ~/.codex에 반영한 뒤 check까지 실행합니다.',
+      ],
+      options: [
+        { flag: '--dir <path>', description: '관리용 skills 저장소를 둘 경로 지정' },
+        { flag: '--cwd <path>', description: '상태/백업 기준 프로젝트 경로 지정' },
+        { flag: '--repo <url>', description: '초기화에 사용할 원격 저장소 URL 지정' },
+        { flag: '--configure-notion', description: 'Notion workspace 설정 파일도 함께 준비' },
+        { flag: '--configure-db-safe-read', description: '현재 track 기준 DB login-path alias 설정' },
+        { flag: '--track <name>', description: 'DB safe-read 설정 시 track을 수동으로 지정' },
+        { flag: '--skip-notion', description: 'Notion 설정 파일 생성을 생략' },
+        { flag: '--dry-run', description: '실제 파일을 쓰지 않고 변경 결과만 확인' },
+        { flag: '--verbose', description: '동기화/백업 경로를 자세히 출력' },
+      ],
+      examples: [
+        'sk setup',
+        'sk setup --configure-notion',
+        'sk setup --configure-db-safe-read --track seokang-skill',
+      ],
+    },
+    init: {
+      title: 'sk init - 현재 프로젝트 초기화',
+      usage: 'sk init [--cwd <path>] [--agent-md] [--dry-run] [--force] [--verbose]',
+      summary: [
+        '현재 프로젝트의 .sk 상태 파일을 준비합니다.',
+        '--agent-md를 붙이면 프로젝트 루트에 AGENT.MD 초안도 함께 생성합니다.',
+      ],
+      options: [
+        { flag: '--cwd <path>', description: '다른 프로젝트 경로를 대상으로 실행' },
+        { flag: '--agent-md', description: '프로젝트 루트 AGENT.MD 초안을 함께 생성' },
+        { flag: '--dry-run', description: '실제 파일을 만들지 않고 결과만 미리 확인' },
+        { flag: '--force', description: '이미 있는 .sk / AGENT.MD도 기본 템플릿으로 다시 생성' },
+        { flag: '--verbose', description: '생성한 파일 경로를 자세히 출력' },
+      ],
+      examples: [
+        'sk init',
+        'sk init --agent-md',
+        'sk init --cwd /path/to/project --agent-md --dry-run',
+      ],
+      generatedFiles: [
+        '.sk/setup-scope.json',
+        '.sk/project-memory.json',
+        '.sk/notepad.md',
+        'AGENT.MD (--agent-md를 붙였을 때만 생성)',
+      ],
+    },
+    check: {
+      title: 'sk check - 설치 차이 점검',
+      usage: 'sk check [--cwd <path>] [--json]',
+      summary: [
+        '공용 원본과 현재 설치 상태가 같은지 확인합니다.',
+        'Notion 설정, DB safe-read alias, 상태 파일 존재 여부도 함께 점검합니다.',
+      ],
+      options: [
+        { flag: '--cwd <path>', description: '점검 기준 프로젝트 경로 지정' },
+        { flag: '--json', description: '점검 결과를 JSON으로 출력' },
+      ],
+      examples: [
+        'sk check',
+        'sk check --cwd /path/to/project',
+        'sk check --json',
+      ],
+    },
+    status: {
+      title: 'sk status - 현재 프로젝트 상태 보기',
+      usage: 'sk status [--cwd <path>] [--json]',
+      summary: [
+        '.sk 상태, AGENT.MD 존재 여부, Notion 설정 상태, 최근 백업, check 결과를 함께 보여줍니다.',
+      ],
+      options: [
+        { flag: '--cwd <path>', description: '상태를 볼 프로젝트 경로 지정' },
+        { flag: '--json', description: '상태 결과를 JSON으로 출력' },
+      ],
+      examples: [
+        'sk status',
+        'sk status --cwd /path/to/project',
+        'sk status --json',
+      ],
+    },
+    memory: {
+      title: 'sk memory - 프로젝트 메모 관리',
+      usage: 'sk memory <show|init|add-note|add-directive> [options]',
+      summary: [
+        '.sk/project-memory.json 과 .sk/notepad.md 를 읽고 갱신하는 보조 명령입니다.',
+      ],
+      options: [
+        { flag: 'show', description: '현재 프로젝트 메모와 메모장 경로/상태 출력' },
+        { flag: 'init', description: '메모 파일을 기본 템플릿으로 준비' },
+        { flag: 'add-note', description: '--category와 함께 일반 메모 추가' },
+        { flag: 'add-directive', description: '--priority, --context와 함께 지시문 추가' },
+      ],
+      examples: [
+        'sk memory show',
+        'sk memory init --force',
+        'sk memory add-note --category decision "AGENT.MD를 기본 문서로 유지"',
+      ],
+    },
+    search: {
+      title: 'sk search - 로컬 Codex 세션 기록 검색',
+      usage: 'sk search <query> [--cwd <path>] [--limit N] [--since 7d] [--project current] [--case-sensitive] [--json]',
+      summary: [
+        '로컬 transcript에서 예전 작업 맥락을 찾습니다.',
+      ],
+      options: [
+        { flag: '--cwd <path>', description: 'current project 필터 기준 경로 지정' },
+        { flag: '--limit N', description: '반환할 최대 결과 수 지정' },
+        { flag: '--since 7d', description: '최근 기간 기준으로 검색 범위 제한' },
+        { flag: '--project current', description: '현재 프로젝트 cwd 기준으로 결과 필터' },
+        { flag: '--case-sensitive', description: '대소문자 구분 검색' },
+        { flag: '--json', description: '검색 결과를 JSON으로 출력' },
+      ],
+      examples: [
+        'sk search reviewer',
+        'sk search "AGENT.MD" --since 30d',
+        'sk search deploy --project current --limit 20',
+      ],
+    },
+  };
+
+  const help = helpByCommand[command];
+  if (!help) {
+    return [
+      `알 수 없는 도움말 대상입니다: ${command}`,
       '',
-      '💡 참고',
-      '  - 배포된 npm 패키지는 설치 진입점과 디스패처 역할만 합니다.',
-      `  - setup은 수정 가능한 원본 저장소를 ${canonicalRepoRoot()} 경로에 준비합니다.`,
-      '  - setup은 로컬 원본 저장소를 기준으로 config, rules, 공용 agent를 동기화하고 check까지 실행합니다.',
-      '  - setup에 --configure-db-safe-read를 붙이면 현재 프로젝트(track) 기준 DB login-path alias를 sk 안에서 맞출 수 있습니다.',
-      '  - init은 현재 프로젝트 루트에 .sk 상태 파일만 준비합니다.',
-      '  - setup은 ~/.codex/sk/notion/workspace.json 아래에 Notion 설정 파일도 만들 수 있습니다.',
-      `  - 프로젝트 상태는 ${STATE_DIRNAME}/ 아래에 저장됩니다.`,
-      `  - 프로젝트 메모리는 ${STATE_DIRNAME}/${PROJECT_MEMORY_FILE} 에 저장됩니다.`,
-      `  - 공용 메모는 ${STATE_DIRNAME}/${NOTEPAD_FILE} 에 저장됩니다.`,
-      '  - 다른 프로젝트를 대상으로 하려면 cd 대신 init/status/memory에 --cwd <path>를 사용할 수 있습니다.',
-      '  - user 설정은 $CODEX_HOME 또는 ~/.codex를 대상으로 사용합니다.',
-      '  - Notion 기록이 invalid_grant/unauthorized/forbidden 같은 인증 오류로 실패하면 "codex mcp login notion"으로 MCP 인증을 다시 연결하세요.',
-      `  - 자세한 가이드: ${guidePath}`,
-    ].join('\n'),
-  );
+      '📝 사용 가능한 상세 도움말:',
+      '  sk help setup',
+      '  sk help init',
+      '  sk help check',
+      '  sk help status',
+      '  sk help memory',
+      '  sk help search',
+    ];
+  }
+
+  const lines = [
+    help.title,
+    '',
+    '🧭 사용법',
+    `  ${help.usage}`,
+    '',
+    '📖 설명',
+    ...help.summary.map((line) => `  - ${line}`),
+    '',
+    '⚙️ 옵션',
+    ...formatOptionLines(help.options),
+    '',
+    '🧪 예시',
+    ...help.examples.map((line) => `  ${line}`),
+  ];
+
+  if (help.generatedFiles) {
+    lines.push('', '📦 생성 파일', ...help.generatedFiles.map((line) => `  - ${line}`));
+  }
+
+  lines.push('', '💡 팁', '  전체 명령 요약은 "sk help"로 다시 볼 수 있습니다.');
+  return lines;
+}
+
+function printUsage(command = 'general') {
+  const normalized = String(command || 'general').toLowerCase();
+  const lines = normalized === 'general' ? generalHelpLines() : commandHelpLines(normalized);
+  console.log(lines.join('\n'));
 }
 
 function fail(message, exitCode = 1) {
@@ -682,7 +858,7 @@ function parseFlags(args) {
       continue;
     }
 
-    if (token === '--json' || token === '--dry-run' || token === '--verbose' || token === '--case-sensitive' || token === '--force' || token === '--configure-notion' || token === '--configure-db' || token === '--configure-db-safe-read' || token === '--skip-notion') {
+    if (token === '--json' || token === '--dry-run' || token === '--verbose' || token === '--case-sensitive' || token === '--force' || token === '--configure-notion' || token === '--configure-db' || token === '--configure-db-safe-read' || token === '--skip-notion' || token === '--agent-md') {
       flags.set(token.slice(2), true);
       continue;
     }
@@ -752,6 +928,219 @@ function createDefaultNotepad() {
   ].join('\n');
 }
 
+function pathExists(cwd, relPath) {
+  return existsSync(join(cwd, ...relPath.split('/').filter(Boolean)));
+}
+
+function firstExistingPath(cwd, candidates) {
+  return candidates.find((candidate) => pathExists(cwd, candidate)) || null;
+}
+
+function formatBullets(items, fallback = 'TODO: Add project-specific guidance here.') {
+  const lines = items.length > 0 ? items : [fallback];
+  return `${lines.map((item) => (item.startsWith('- ') ? item : `- ${item}`)).join('\n')}\n`;
+}
+
+function detectNodePackageManager(cwd) {
+  if (existsSync(join(cwd, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (existsSync(join(cwd, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
+function formatRunScriptCommand(packageManager, scriptName) {
+  if (packageManager === 'yarn') return `yarn ${scriptName}`;
+  if (packageManager === 'pnpm') return `pnpm ${scriptName}`;
+  return `npm run ${scriptName}`;
+}
+
+async function readPackageManifest(cwd) {
+  return readJsonOptional(join(cwd, 'package.json'));
+}
+
+function inferAgentTemplateKind(cwd, track) {
+  if (track === 'seokang-skill') return 'codex';
+  if (track === 'server' || track === 'slk-server') return 'backend';
+  if (track) return 'frontend';
+
+  if (pathExists(cwd, 'skills') && pathExists(cwd, 'codex-config')) {
+    return 'codex';
+  }
+
+  if (['gradlew', 'pom.xml', 'build.gradle', 'build.gradle.kts', 'src/main'].some((relPath) => pathExists(cwd, relPath))) {
+    return 'backend';
+  }
+
+  return 'frontend';
+}
+
+function buildAgentEntryPoints(kind, cwd) {
+  const items = [];
+  const readmePath = firstExistingPath(cwd, ['README.MD', 'README.md', 'README']);
+  if (readmePath) {
+    items.push(`\`${readmePath}\`: 프로젝트 개요와 설치/운영 문서`);
+  }
+
+  if (kind === 'codex') {
+    if (pathExists(cwd, 'skills')) items.push('`skills/`: 공용 skill 원본과 workflow 규칙');
+    if (pathExists(cwd, 'codex-config')) items.push('`codex-config/`: 동기화 대상 Codex config / rules / agents 원본');
+    if (pathExists(cwd, 'scripts')) items.push('`scripts/`: 설치/동기화 스크립트와 CLI 진입점');
+    if (pathExists(cwd, 'docs')) items.push('`docs/`: 운영 가이드와 변경 문서');
+  } else if (kind === 'backend') {
+    const mainPath = firstExistingPath(cwd, ['src/main/java', 'src/main/kotlin', 'src/main']);
+    const testPath = firstExistingPath(cwd, ['src/test/java', 'src/test/kotlin', 'src/test']);
+    const resourcePath = firstExistingPath(cwd, ['src/main/resources', 'resources']);
+    const dbPath = firstExistingPath(cwd, ['src/main/resources/db', 'db', 'database', 'sql']);
+    if (mainPath) items.push(`\`${mainPath}/\`: 서버 소스와 주요 엔트리포인트`);
+    if (testPath) items.push(`\`${testPath}/\`: 회귀 테스트와 검증 코드`);
+    if (resourcePath) items.push(`\`${resourcePath}/\`: 설정, profile, 리소스 파일`);
+    if (dbPath) items.push(`\`${dbPath}/\`: SQL, 마이그레이션, DB 관련 산출물`);
+    if (pathExists(cwd, 'docs')) items.push('`docs/`: 운영/계약/변경 문서');
+  } else {
+    const routePath = firstExistingPath(cwd, ['src/routes', 'src/pages', 'src/app', 'app']);
+    const componentPath = firstExistingPath(cwd, ['src/components', 'components']);
+    const assetPath = firstExistingPath(cwd, ['public', 'src/assets', 'assets']);
+    if (pathExists(cwd, 'src')) items.push('`src/`: 화면, 상태, 도메인 로직의 기본 소스');
+    if (routePath) items.push(`\`${routePath}/\`: 주요 라우트와 화면 진입점`);
+    if (componentPath) items.push(`\`${componentPath}/\`: 공통 UI와 재사용 컴포넌트`);
+    if (assetPath) items.push(`\`${assetPath}/\`: 정적 파일과 이미지 자산`);
+    if (pathExists(cwd, 'docs')) items.push('`docs/`: 화면 흐름/운영/변경 문서');
+  }
+
+  items.push('`.sk/`: 세션 메모와 작업 상태 파일');
+  return formatBullets(items, 'TODO: 이 프로젝트의 핵심 소스 디렉터리와 엔트리포인트를 채워 주세요.');
+}
+
+function buildRunbookFromPackageScripts(cwd, manifest, preferredScripts) {
+  const scripts = manifest && typeof manifest.scripts === 'object' ? manifest.scripts : null;
+  if (!scripts) return [];
+
+  const packageManager = detectNodePackageManager(cwd);
+  const descriptions = {
+    dev: '로컬 개발 서버 실행',
+    start: '기본 실행 명령',
+    build: '빌드 산출물 생성',
+    test: '기본 테스트 실행',
+    typecheck: '타입 검사',
+    lint: '정적 규칙 검사',
+  };
+
+  return preferredScripts
+    .filter((scriptName) => Object.prototype.hasOwnProperty.call(scripts, scriptName))
+    .map((scriptName) => `\`${formatRunScriptCommand(packageManager, scriptName)}\`: ${descriptions[scriptName] || '프로젝트 기본 스크립트'}`);
+}
+
+function buildAgentRunbook(kind, cwd, manifest) {
+  const items = [
+    '`sk init --agent-md` 또는 `sk init --cwd <path> --agent-md`: 프로젝트 상태 파일과 AGENT.MD 초안 생성',
+  ];
+
+  if (kind === 'codex') {
+    items.push('`sk setup`: 공용 config / rules / agents 동기화');
+    items.push('`sk check`: 공용 원본과 설치 차이 점검');
+    items.push('`sk status`: 현재 .sk / AGENT.MD / Notion 설정 상태 확인');
+    return formatBullets(items);
+  }
+
+  if (pathExists(cwd, 'gradlew')) {
+    items.push('`./gradlew test`: 기본 회귀 테스트');
+    items.push('`./gradlew build`: 빌드/패키징 확인');
+    return formatBullets(items);
+  }
+
+  if (pathExists(cwd, 'mvnw')) {
+    items.push('`./mvnw test`: 기본 테스트');
+    items.push('`./mvnw verify`: 검증 포함 빌드');
+    return formatBullets(items);
+  }
+
+  const scriptItems = buildRunbookFromPackageScripts(
+    cwd,
+    manifest,
+    kind === 'backend'
+      ? ['start', 'dev', 'test', 'build', 'lint']
+      : ['dev', 'start', 'typecheck', 'test', 'build', 'lint'],
+  );
+  if (scriptItems.length > 0) {
+    items.push(...scriptItems);
+    return formatBullets(items);
+  }
+
+  items.push('TODO: 이 프로젝트에서 실제로 쓰는 설치/실행/테스트 명령으로 교체해 주세요.');
+  return formatBullets(items);
+}
+
+function buildAgentValidation(kind, cwd, manifest) {
+  const items = [];
+
+  if (kind === 'codex') {
+    items.push('`sk init --cwd <path> --agent-md --dry-run`: 새 프로젝트 초기화 결과 미리보기');
+    items.push('`sk status`와 `sk check`: 상태 파일, AGENT.MD, 설치 차이 확인');
+    items.push('설치/설정 변경이면 실제 홈 반영 전에 임시 `CODEX_HOME`에서 한 번 더 검증');
+    return formatBullets(items);
+  }
+
+  if (kind === 'backend') {
+    if (pathExists(cwd, 'gradlew')) {
+      items.push('`./gradlew test`와 `./gradlew build`를 기본 회귀 검증으로 사용');
+    } else if (pathExists(cwd, 'mvnw')) {
+      items.push('`./mvnw test`와 `./mvnw verify`를 기본 회귀 검증으로 사용');
+    } else {
+      const scriptItems = buildRunbookFromPackageScripts(cwd, manifest, ['test', 'build', 'lint']);
+      if (scriptItems.length > 0) items.push(...scriptItems);
+    }
+    items.push('변경한 API 또는 저장 흐름에 대해 최소 1개의 startup/context 검증 경로를 남긴다.');
+    items.push('Profile, secret, seed data, 외부 의존성 필요 여부를 이 파일이나 docs에 명시한다.');
+    return formatBullets(items);
+  }
+
+  const scriptItems = buildRunbookFromPackageScripts(cwd, manifest, ['typecheck', 'test', 'build', 'lint']);
+  if (scriptItems.length > 0) {
+    items.push(...scriptItems);
+  } else {
+    items.push('TODO: 이 UI 프로젝트에서 실제로 쓰는 테스트/typecheck/build 명령을 채워 주세요.');
+  }
+  items.push('영향 받은 화면/라우트에서 런타임 동작, 콘솔 에러, 필요한 계정/데이터 전제조건을 함께 검증한다.');
+  items.push('고객 노출 UI면 실제 뷰포트 기준 시각 검증 경로를 남긴다.');
+  return formatBullets(items);
+}
+
+function buildAgentTemplateContext(cwd, manifest) {
+  const track = inferTrackFromPath(cwd) || '수동확인필요';
+  const templateKind = inferAgentTemplateKind(cwd, track);
+  const projectName = isNonEmptyString(manifest?.name) ? manifest.name.trim() : basename(cwd);
+  return {
+    projectName,
+    track,
+    templateKind,
+    entryPoints: buildAgentEntryPoints(templateKind, cwd),
+    runbook: buildAgentRunbook(templateKind, cwd, manifest),
+    validation: buildAgentValidation(templateKind, cwd, manifest),
+  };
+}
+
+async function renderAgentTemplate(cwd = process.cwd()) {
+  const manifest = await readPackageManifest(cwd);
+  const context = buildAgentTemplateContext(cwd, manifest);
+  const baseTemplate = await readFile(agentTemplatePath('base.md'), 'utf-8');
+  const overlayTemplate = await readFile(agentTemplatePath(`${context.templateKind}.md`), 'utf-8');
+
+  let content = baseTemplate.replace('__TRACK_CONTENT__', overlayTemplate.trim());
+  const replacements = [
+    ['__PROJECT_NAME__', context.projectName],
+    ['__TRACK__', context.track],
+    ['__TEMPLATE_KIND__', context.templateKind],
+    ['__ENTRY_POINTS__', context.entryPoints.trimEnd()],
+    ['__RUNBOOK__', context.runbook.trimEnd()],
+    ['__VALIDATION__', context.validation.trimEnd()],
+  ];
+
+  for (const [token, value] of replacements) {
+    content = content.replaceAll(token, value);
+  }
+
+  return `${content.trimEnd()}\n`;
+}
+
 function createDefaultNotionWorkspaceConfig() {
   return {
     version: 1,
@@ -1294,6 +1683,30 @@ async function ensureProjectStateFiles({
   return summary;
 }
 
+async function ensureProjectAgentFile({
+  cwd = process.cwd(),
+  dryRun = false,
+  verbose = false,
+  force = false,
+}) {
+  const summary = createSummaryEntry();
+  const targetPath = agentMdPath(cwd);
+  const content = await renderAgentTemplate(cwd);
+
+  if (!existsSync(targetPath) || force) {
+    if (!dryRun) {
+      await ensureDir(dirname(targetPath));
+      await writeFile(targetPath, content, 'utf-8');
+    }
+    if (verbose) console.log(`  ✍️  기록: ${targetPath}`);
+    summary.updated += 1;
+  } else {
+    summary.unchanged += 1;
+  }
+
+  return summary;
+}
+
 async function readPersistedScope(cwd = process.cwd()) {
   const path = scopeFilePath(cwd);
   if (!existsSync(path)) return null;
@@ -1534,6 +1947,7 @@ async function runInit(flags) {
   const dryRun = Boolean(flags.get('dry-run'));
   const verbose = Boolean(flags.get('verbose'));
   const force = Boolean(flags.get('force'));
+  const createAgentMd = Boolean(flags.get('agent-md'));
 
   if (!flags.get('cwd') && samePath(cwd, homedir())) {
     fail('sk init은 프로젝트 루트에서 실행하세요. 홈 디렉터리에서 실행하려면 --cwd <path>로 프로젝트 경로를 지정하세요.');
@@ -1541,14 +1955,21 @@ async function runInit(flags) {
 
   const scopePath = await writeScopeFile('project', cwd, dryRun);
   const stateSummary = await ensureProjectStateFiles({ cwd, dryRun, verbose, force });
+  const agentSummary = createAgentMd
+    ? await ensureProjectAgentFile({ cwd, dryRun, verbose, force })
+    : createSummaryEntry();
 
   console.log(`sk init${dryRun ? ' (dry-run)' : ''}`);
   console.log(`  🗂️  상태 파일: ${scopePath}`);
   console.log(`  🧠 프로젝트 메모리: ${projectMemoryPath(cwd)}`);
   console.log(`  📒 메모장: ${notepadPath(cwd)}`);
+  if (createAgentMd || existsSync(agentMdPath(cwd))) {
+    console.log(`  📄 AGENT.MD: ${agentMdPath(cwd)}`);
+  }
   console.log(
     `  📊 요약: 메모리(갱신=${stateSummary.memory.updated}, 유지=${stateSummary.memory.unchanged}) ` +
-      `메모장(갱신=${stateSummary.notepad.updated}, 유지=${stateSummary.notepad.unchanged})`,
+      `메모장(갱신=${stateSummary.notepad.updated}, 유지=${stateSummary.notepad.unchanged})` +
+      `${createAgentMd ? ` AGENT.MD(갱신=${agentSummary.updated}, 유지=${agentSummary.unchanged})` : ''}`,
   );
   console.log('  ✅ 현재 프로젝트의 .sk 상태가 준비되었습니다.');
 }
@@ -1647,6 +2068,10 @@ async function buildDoctorResult(cwd = process.cwd()) {
     ? check('pass', '메모장', notepadPath(cwd))
     : check('warn', '메모장', `${notepadPath(cwd)} 파일이 없습니다.`));
 
+  if (existsSync(agentMdPath(cwd))) {
+    checks.push(check('pass', 'AGENT.MD', agentMdPath(cwd)));
+  }
+
   checks.push(...buildDbSafeReadChecks(cwd));
 
   if (!existsSync(target.notionConfigPath)) {
@@ -1708,6 +2133,8 @@ async function runStatus(flags) {
     project_memory_exists: existsSync(projectMemoryPath(cwd)),
     notepad_path: notepadPath(cwd),
     notepad_exists: existsSync(notepadPath(cwd)),
+    agent_md_path: agentMdPath(cwd),
+    agent_md_exists: existsSync(agentMdPath(cwd)),
     notes_count: memory?.notes.length ?? 0,
     directives_count: memory?.directives.length ?? 0,
     notion_config_path: target.notionConfigPath,
@@ -1730,6 +2157,7 @@ async function runStatus(flags) {
   console.log(`  🗂️  상태 디렉터리: ${status.state_dir}`);
   console.log(`  🧠 프로젝트 메모리: ${status.project_memory_exists ? '있음' : '없음'} (${status.project_memory_path})`);
   console.log(`  📒 메모장: ${status.notepad_exists ? '있음' : '없음'} (${status.notepad_path})`);
+  console.log(`  📄 AGENT.MD: ${status.agent_md_exists ? '있음' : '없음'} (${status.agent_md_path})`);
   console.log(`  📝 Notion 설정: ${status.notion_config_exists ? (status.notion_configured ? '설정 완료' : '불완전') : '없음'} (${status.notion_config_path})`);
   console.log(`  📌 메모/지시문: ${status.notes_count}/${status.directives_count}`);
   console.log(`  💾 최근 백업: ${status.latest_backup || '없음'}`);
@@ -2149,11 +2577,17 @@ async function runMemory(flags, rest) {
 
 async function main() {
   const [command, ...args] = process.argv.slice(2);
-  if (!command || command === 'help' || command === '--help' || command === '-h') {
+  if (!command || command === '--help' || command === '-h') {
     printUsage();
     return;
   }
 
+  if (command === 'help') {
+    const target = args[0];
+    printUsage(target || 'general');
+    return;
+  }
+
   const localDispatcher = resolveLocalDispatcher(command);
   if (localDispatcher) {
     runCommandOrFail(process.execPath, [localDispatcher, command, ...args], {
@@ -2179,7 +2613,7 @@ async function main() {
   if (command === 'search') {
     const { flags, rest } = parseFlags(args);
     if (flags.get('help')) {
-      printUsage();
+      printUsage('search');
       return;
     }
     await runSessionSearch(flags, ['search', ...rest]);
@@ -2189,7 +2623,7 @@ async function main() {
   if (command === 'memory') {
     const { flags, rest } = parseFlags(args);
     if (flags.get('help')) {
-      printUsage();
+      printUsage('memory');
       return;
     }
     await runMemory(flags, rest);
@@ -2198,7 +2632,7 @@ async function main() {
 
   const { flags } = parseFlags(args);
   if (flags.get('help')) {
-    printUsage();
+    printUsage(command);
     return;
   }
 

package/templates/agent/backend.md

@@ -0,0 +1,22 @@
+## 목적
+- TODO: `__PROJECT_NAME__`가 책임지는 범위와 반드시 안정적으로 유지해야 하는 외부 계약을 적습니다.
+- API, 인증, 저장소, 운영 가드레일은 여기에서 바로 확인할 수 있게 유지합니다.
+
+## 주요 진입점
+__ENTRY_POINTS__
+
+## 실행/작업 명령
+__RUNBOOK__
+
+## 작업 규칙
+- 코드 수정 전에는 이 파일을 먼저 읽고, 그다음 `.sk/project-memory.json`, `.sk/notepad.md`, 관련 README/docs를 확인합니다.
+- 동작을 바꿀 때는 controller/service/repository 경계와 외부 응답 계약이 의도적으로 유지되는지 확인합니다.
+- DB 확인은 safe-read 근거 확보를 우선하고, 일상 워크플로에 raw credential이나 write query를 남기지 않습니다.
+- 검증에 필요한 profile, secret, queue, storage, seed data 전제조건을 문서화합니다.
+
+## 검증 기준
+__VALIDATION__
+
+## 문서/기록
+- 백엔드 동작이 바뀌면 영향받는 API 경로, profile, rollout 메모, rollback 지점을 함께 남깁니다.
+- 기준 문서가 코드 밖에 있으면 계약을 정의한 docs/spec 링크를 연결합니다.

package/templates/agent/base.md

@@ -0,0 +1,18 @@
+<!-- `sk init --agent-md`로 생성한 초안입니다. 첫 프로젝트 맞춤 정리 이후 임시 문구를 교체하세요. -->
+# AGENT.MD
+
+> Codex와 팀원이 함께 따르는 프로젝트 단위 작업 기준서입니다.
+> README보다 짧게 유지하고, 임시 메모는 `.sk/notepad.md`로 분리합니다.
+
+## 프로젝트 개요
+- 이름: `__PROJECT_NAME__`
+- 트랙: `__TRACK__`
+- 템플릿: `__TEMPLATE_KIND__`
+- 생성 명령: `sk init --agent-md`
+
+__TRACK_CONTENT__
+
+## 작성 체크리스트
+- 아직 `TODO`로 남아 있는 항목은 프로젝트 기준으로 교체합니다.
+- 긴 설치 가이드나 제품 배경 설명은 여기보다 `README` 또는 `docs/`에 둡니다.
+- 워크플로, 검증 방식, 배포 규칙이 바뀌면 이 파일도 함께 갱신합니다.

package/templates/agent/codex.md

@@ -0,0 +1,22 @@
+## 목적
+- `__PROJECT_NAME__`를 공용 Codex 워크플로, 설치/동기화, 문서 규칙의 기준 원본으로 사용합니다.
+- 장기 수정은 여기 원본 파일에 먼저 반영하고, 생성된 실행 환경 파일만 임시로 고치고 끝내지 않습니다.
+
+## 주요 진입점
+__ENTRY_POINTS__
+
+## 실행/작업 명령
+__RUNBOOK__
+
+## 작업 규칙
+- `~/.codex` 아래 생성 파일보다 저장소 원본 (`skills/`, `codex-config/`, `scripts/`, `docs/`)을 우선 수정합니다.
+- 설치/동기화 설정 변경은 실제 사용자 환경 재동기화 전에 임시 환경에서 먼저 검증합니다.
+- 프로젝트 단위의 고정 규칙은 여기에 두고, 세션 전용 메모는 `.sk/notepad.md`로 분리합니다.
+- 같은 워크플로 문제가 반복되면 임시 로컬 수정이 아니라 원인이 된 skill/doc/설치 경로를 고칩니다.
+
+## 검증 기준
+__VALIDATION__
+
+## 문서/기록
+- 명령이나 워크플로를 바꾸면 같은 변경 안에서 README/docs도 함께 반영합니다.
+- Notion 기록과 대체 문서 동작은 이 저장소의 기준 워크플로와 맞춰 유지합니다.

package/templates/agent/frontend.md

@@ -0,0 +1,22 @@
+## 목적
+- TODO: `__PROJECT_NAME__`가 책임지는 화면/흐름과 의도적으로 제외한 범위를 짧게 정리합니다.
+- 고객에게 보이는 흐름, 카피, 승인 조건은 여기서 바로 찾을 수 있게 유지합니다.
+
+## 주요 진입점
+__ENTRY_POINTS__
+
+## 실행/작업 명령
+__RUNBOOK__
+
+## 작업 규칙
+- 라우트나 화면을 수정하기 전에는 이 파일을 먼저 읽고, 그다음 `.sk/project-memory.json`, `.sk/notepad.md`, 관련 README/docs를 확인합니다.
+- 고객 노출 UI, 라우트 흐름, 승인된 디자인/스펙 동작은 합의된 기준 문서와 맞춰 유지합니다.
+- 원격 디자인 파일 URL을 코드나 설정에 남기지 말고, export한 파일은 프로젝트 내부에 저장합니다.
+- 대상 화면을 재현하는 데 필요한 라우트, 권한, fixture, 테스트 데이터 전제조건을 적어 둡니다.
+
+## 검증 기준
+__VALIDATION__
+
+## 문서/기록
+- 화면 변경이 보이는 작업이면 라우트/화면 이름, 필요한 계정/권한, 런타임 검증 경로를 함께 남깁니다.
+- 흐름, 카피, 가드레일이 바뀌면 연결된 스펙/docs도 같이 갱신합니다.