jutell 1.0.1 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. package/README.md +39 -17
  2. package/assets/local-admin/index.html +12 -12
  3. package/assets/mcp-server/index.js +7 -7
  4. package/assets/skill/SKILL.md +139 -137
  5. package/assets/skill/references/feature-registry.md +29 -29
  6. package/assets/skill/references/glossary-ko.md +302 -302
  7. package/assets/skill/references/report-format.md +203 -203
  8. package/assets/skill/references/risk-level-guide.md +85 -85
  9. package/assets/templates/request-builder/BUG_REPORT_REQUEST.md +100 -100
  10. package/assets/templates/request-builder/CODE_REVIEW_REQUEST.md +93 -93
  11. package/assets/templates/request-builder/DESIGN_REQUEST.md +111 -111
  12. package/assets/templates/request-builder/FEATURE_REQUEST.md +93 -93
  13. package/assets/templates/request-builder/MANUAL_EDIT_GUIDE.md +95 -95
  14. package/assets/templates/request-builder/PROJECT_PLANNING_REQUEST.md +106 -106
  15. package/assets/templates/request-builder/README.md +48 -48
  16. package/assets/version.json +1 -1
  17. package/dist/commands/default.js +131 -68
  18. package/dist/commands/provider.js +18 -18
  19. package/dist/commands/session/index.js +16 -16
  20. package/dist/installer/agents.js +9 -8
  21. package/dist/output/format.js +41 -43
  22. package/dist/process/mcpProbe.js +1 -1
  23. package/package.json +55 -55
package/README.md CHANGED
@@ -1,17 +1,39 @@
1
- # jutell
2
-
3
- JuTell by Ju0의 로컬 설치·상태·진단·관리자 실행 CLI입니다. `jutell@1.0.0`은 npm에 공개되었습니다.
4
-
5
- ```powershell
6
- npm install -g jutell
7
- jutell use codex
8
- jutell status
9
- ```
10
-
11
- 개발자·기여자용 로컬 설치 (일반 사용자는 위 registry 설치 사용):
12
-
13
- ```bash
14
- npm install -g ./jutell-1.0.1.tgz
15
- ```
16
-
17
- 기존 `beginner-bridge` 명령은 같은 기능의 호환 별칭이며 실행 시 새 명령 사용을 안내합니다. CLI는 프로젝트 코드, Prompt, AI 답변, Git diff와 비밀정보를 수집하거나 외부로 전송하지 않습니다.
1
+ # jutell
2
+
3
+ **Your coding agent writes the code. JuTell helps you understand what happened.**
4
+
5
+ JuTell sits beside Codex, Claude Code, or OpenCode and turns their work into a plain-language report: what changed, what's actually verified, what's still unknown, and what to do next.
6
+
7
+ ```bash
8
+ npm install -g jutell
9
+ jutell
10
+ ```
11
+
12
+ `jutell` finds the coding agents you already have installed, asks for one approval, connects them, and hands you straight back to your normal session — no per-agent setup command needed for a normal first run.
13
+
14
+ | Agent | Status |
15
+ |---|---|
16
+ | Codex | Supported |
17
+ | Claude Code | Beta |
18
+ | OpenCode | Beta |
19
+
20
+ To connect (or reconnect) one specific agent by hand, use `jutell use codex` / `jutell use claude` / `jutell use opencode` — this is the manual/repair path, not the normal first run.
21
+
22
+ **한국어 사용자라면:** 전체 문서와 한국어 안내는 [GitHub 저장소의 README.ko.md](https://github.com/ju0o/jutell/blob/main/README.ko.md)에 있습니다.
23
+
24
+ Full docs, images, and the complete feature walkthrough live on [GitHub](https://github.com/ju0o/jutell#readme).
25
+
26
+ <details>
27
+ <summary>Build from source instead (contributors / verifying the repo directly)</summary>
28
+
29
+ Most people should use the npm install above.
30
+
31
+ ```bash
32
+ cd packages/cli
33
+ npm install
34
+ npm pack
35
+ npm install -g ./jutell-1.1.0.tgz
36
+ ```
37
+ </details>
38
+
39
+ The legacy `beginner-bridge` command is a compatibility alias for the same functionality and tells you to switch to `jutell` when you run it. The CLI does not collect or transmit your project code, prompts, AI answers, Git diffs, or secrets.
package/assets/local-admin/index.html CHANGED
@@ -1,14 +1,14 @@
1
- <!doctype html>
2
- <html lang="ko">
3
- <head>
4
- <meta charset="UTF-8" />
5
- <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
- <meta name="description" content="JuTell by Ju0 개인 베타 로컬 관리자" />
7
- <title>JuTell 개인 베타 관리자</title>
1
+ <!doctype html>
2
+ <html lang="ko">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
+ <meta name="description" content="JuTell by Ju0 개인 베타 로컬 관리자" />
7
+ <title>JuTell 개인 베타 관리자</title>
8
8
  <script type="module" crossorigin src="/assets/index-4Pw2ygFb.js"></script>
9
9
  <link rel="stylesheet" crossorigin href="/assets/index-CVml-p-C.css">
10
- </head>
11
- <body>
12
- <div id="root"></div>
13
- </body>
14
- </html>
10
+ </head>
11
+ <body>
12
+ <div id="root"></div>
13
+ </body>
14
+ </html>
package/assets/mcp-server/index.js CHANGED
@@ -5,9 +5,9 @@ import { activeFeatures, beginnerReportRules, bridgeStatus, reportPreferences, s
5
5
  import { recordToolCall } from './tools/usage-counters.js';
6
6
  const server = new McpServer({
7
7
  name: 'JuTell',
8
- version: '1.0.1',
8
+ version: '1.1.0',
9
9
  }, {
10
- instructions: 'JuTell by Ju0 is a local read-only report helper. Read only project configuration and approved report rules. Never access project code, Git diff, prompts, AI answers, secrets, or external networks. Skill mode remains available if this MCP server is disabled or unavailable. When both jutell and beginner_bridge servers are visible, prefer the canonical jutell server; use beginner_bridge only for compatibility. For owner-facing reports, apply the JuTell reporting guidance before composing the final answer.',
10
+ instructions: 'JuTell by Ju0 is a local read-only report helper. Read only project configuration and approved report rules. Never access project code, Git diff, prompts, AI answers, secrets, or external networks. Skill mode remains available if this MCP server is disabled or unavailable. When both jutell and beginner_bridge servers are visible, prefer the canonical jutell server; use beginner_bridge only for compatibility. For owner-facing reports, apply the JuTell reporting guidance before composing the final answer. Prefer these tools over re-reading the JuTell Skill reference files when both are available, since a tool call returns the same project-specific rules in one step. Call get_beginner_report_rules once, at task completion, right before writing the final report — not after every file read, shell command, or edit, and not to verify work that is already done. If these tools are unavailable or blocked, fall back to the JuTell Skill files without interrupting the task, and never tell the user JuTell MCP was used unless a JuTell tool call actually returned a result in this task.',
11
11
  });
12
12
  const noInput = { inputSchema: {} };
13
13
  async function counted(toolName, run) {
@@ -19,23 +19,23 @@ async function counted(toolName, run) {
19
19
  await recordToolCall(toolName, characters);
20
20
  return result;
21
21
  }
22
- server.registerTool('get_bridge_status', { ...noInput, description: 'Return local JuTell configuration and availability status.' }, async () => counted('get_bridge_status', async () => {
22
+ server.registerTool('get_bridge_status', { ...noInput, description: 'Diagnostic only: return whether JuTell is configured and enabled for this project. Use when JuTell setup itself looks wrong (e.g. reports seem to ignore .jutell.json), not as part of a normal report — get_beginner_report_rules already includes what a report needs. Does not read project code or Git.' }, async () => counted('get_bridge_status', async () => {
23
23
  const context = await readBridgeContext();
24
24
  return { content: [{ type: 'text', text: JSON.stringify(bridgeStatus(context)) }] };
25
25
  }));
26
- server.registerTool('get_active_features', { ...noInput, description: 'Return active JuTell features and their safe omissions.' }, async () => counted('get_active_features', async () => {
26
+ server.registerTool('get_active_features', { ...noInput, description: 'Diagnostic only: list which JuTell report sections are on/off and what each safely omits when off. Use only when you need to explain JuTell\'s own configuration to the user; get_beginner_report_rules already returns the active sections needed to write a report, so call this instead of that only for that narrower question.' }, async () => counted('get_active_features', async () => {
27
27
  const context = await readBridgeContext();
28
28
  return { content: [{ type: 'text', text: JSON.stringify({ features: activeFeatures(context.config) }) }] };
29
29
  }));
30
- server.registerTool('get_report_preferences', { ...noInput, description: 'Return the current report Profile and limits.' }, async () => counted('get_report_preferences', async () => {
30
+ server.registerTool('get_report_preferences', { ...noInput, description: 'Diagnostic only: return the report Profile (minimal/balanced/learning/detailed) and length/file/glossary limits. Use only when asked how JuTell is configured; get_beginner_report_rules already includes these limits for normal report writing.' }, async () => counted('get_report_preferences', async () => {
31
31
  const context = await readBridgeContext();
32
32
  return { content: [{ type: 'text', text: JSON.stringify(reportPreferences(context.config)) }] };
33
33
  }));
34
- server.registerTool('get_beginner_report_rules', { ...noInput, description: 'Return only the active report rules needed for the current project configuration.' }, async () => counted('get_beginner_report_rules', async () => {
34
+ server.registerTool('get_beginner_report_rules', { ...noInput, description: 'The primary report-writing tool: returns this project\'s active report rules (which sections to include, length/voice limits, the evidence/status/diff rules, safety requirements) in one call. Call this once, right before writing the final owner-facing report for a completed task — it replaces reading report-format.md, risk-level-guide.md, and related Skill reference files by hand. Do not call it for non-report answers (plain questions, explanations, plans), and do not call it more than once per task just to double-check.' }, async () => counted('get_beginner_report_rules', async () => {
35
35
  const context = await readBridgeContext();
36
36
  return { content: [{ type: 'text', text: JSON.stringify(beginnerReportRules(context.config)) }] };
37
37
  }));
38
- server.registerTool('get_safe_report_requirements', { ...noInput, description: 'Return information that must never be hidden from a final report.' }, async () => counted('get_safe_report_requirements', async () => {
38
+ server.registerTool('get_safe_report_requirements', { ...noInput, description: 'Return the fixed list of items (failures, unresolved risks, secrets exposure, data loss, out-of-scope changes) that a report must never omit, even when the active Profile would otherwise skip them. Use alongside get_beginner_report_rules only when a report involves a failure, risk, or safety-relevant change — most routine reports do not need a separate call for this.' }, async () => counted('get_safe_report_requirements', async () => {
39
39
  return { content: [{ type: 'text', text: JSON.stringify(safeReportRequirements()) }] };
40
40
  }));
41
41
  const transport = new StdioServerTransport();
package/assets/skill/SKILL.md CHANGED
@@ -1,137 +1,139 @@
1
- ---
2
- name: beginner-bridge
3
- jutellSkillVersion: "1.0.1"
4
- schemaVersion: 1
5
- description: JuTell by Ju0 creates concise, evidence-based work reports for non-developers, separating observed facts, code-based expectations, verification results, risks, and user actions. The legacy Skill ID is retained for compatibility.
6
- ---
7
-
8
- # JuTell by Ju0
9
-
10
- Codex 작업 결과를 비개발자가 이해할 수 있는 하나의 보고서로 정리한다. 확인하지 않은 내용을 완료된 사실처럼 표현하지 않는다. 제품 목적은 AI가 만든 결과를 사람이 이해하고 운영하도록 돕는 것이다.
11
-
12
- ## 적용 전 읽기
13
-
14
- 필요한 문서만 progressive disclosure 방식으로 읽는다.
15
-
16
- 1. `AGENTS.md`가 있으면 먼저 읽고 시스템·개발자·사용자 지침을 따른다.
17
- 2. 제품 범위나 보고서 규칙이 필요하면 `docs/PRODUCT_SCOPE.md`와 `docs/BEGINNER_REPORT_SPEC.md`를 읽는다.
18
- 3. 용어가 등장하면 `docs/GLOSSARY_POLICY.md`와 `references/glossary-ko.md`를 필요한 부분만 읽는다.
19
- 4. 보고서 형식이 필요하면 `references/report-format.md`를 읽는다.
20
- 5. 위험도 판단이 필요하면 `references/risk-level-guide.md`를 읽는다.
21
- 6. V0.1 시나리오나 평가를 수행할 때만 `docs/TEST_SCENARIOS.md`를 읽는다.
22
-
23
- 문서가 없거나 읽을 수 없으면 추측으로 보완하지 말고 그 사실을 보고한다.
24
-
25
- ## 적용하지 않을 상황
26
-
27
- 다음 경우에는 전체 작업 보고서 형식을 강제로 적용하지 않는다.
28
-
29
- * 일반 개발 개념 질문
30
- * 프로젝트와 관계없는 질문
31
- * 단순 용어 뜻 질문
32
- * 사용자가 다른 출력 형식을 명확히 요청한 경우
33
-
34
- 사용자가 상세 보고를 생략해달라고 하면 최소 보고만 제공한다. 작업 완료 여부, 주요 수정 파일, 중요한 실패 또는 미확인 항목은 생략하지 않는다.
35
-
36
- ## 설정 해석 절차
37
-
38
- 실행 절차에 들어가기 전에 다음 순서로 로컬 설정을 해석한다.
39
-
40
- 1. 프로젝트 루트에서 `.jutell.json`을 먼저 확인하고, 없으면 `.beginner-bridge.json`을 호환 경로로 확인한다.
41
- 2. JSON, `version`, Profile, Feature ID, boolean 값과 limits를 검증한다.
42
- 3. 선택한 Profile의 기본값을 적용한다. 파일이 없으면 `balanced`를 사용한다.
43
- 4. 명시적으로 적힌 `features`와 `limits`를 Profile 기본값보다 우선 적용한다.
44
- 5. `voice.preset`이 있으면 보고 문체에만 적용한다. 지원 값: `default`, `plain`, `learning`, `jutell`. 없거나 잘못된 값이면 `default`로 진행한다. 말투를 바꿔도 사실·검증·위험·사용자 행동은 줄이거나 과장하지 않는다.
45
- 6. 안전상 강제 보고 항목과 사용자가 현재 요청에서 요구한 형식을 적용한다.
46
- 7. 이번 보고서에서 사용할 최종 활성 Feature와 limits를 확정한다.
47
- 8. 활성 Feature만 사용해 보고서를 작성하되, 강제 보고 항목은 생략하지 않는다.
48
-
49
- 설정 오류가 있으면 전체 설정을 추측해 고치지 않고 `balanced`로 진행한다. 오류가 있는 경우에만 설정 문제를 짧게 알리며 설정 파일 전체는 출력하지 않는다.
50
-
51
- ## MCP 서버 선택
52
-
53
- JuTell MCP가 보이면 canonical `jutell` 서버를 사용한다. `jutell`과 `beginner_bridge`가 모두 보이면 `jutell`을 우선하고 `beginner_bridge`는 호환용으로만 사용한다.
54
-
55
- ## 실행 절차
56
-
57
- 1. 소유자 대상 구현·보고 작업이면 최종 답변을 작성하기 전에 JuTell 보고 규칙(`get_beginner_report_rules` 등)을 먼저 확인해 적용한다.
58
- 2. 사용자 요청, 작업 유형, 허용 범위와 금지 범위를 확인한다.
59
- 3. 코드 변경 작업이면 가능한 범위에서 작업 시작 기준 상태를 기록한다.
60
- * Git 저장소와 브랜치
61
- * 기존 수정 파일과 추적되지 않은 파일
62
- * 실행 가능한 테스트·빌드·검사 명령
63
- * 브라우저 또는 실제 실행 가능 여부
64
- 4. 기준 상태를 기록하지 못하면 기존 변경과 이번 변경을 임의로 섞지 않는다. Codex가 직접 수정한 사실이 명확한 파일만 이번 변경으로 표시하고 나머지는 출처 구분 불가로 표시한다.
65
- 5. 실제 변경 파일과 내용을 확인한다. 파일명만으로 기능 역할이나 변경 의미를 확정하지 않는다.
66
- 6. 주요 파일을 작업 규모에 맞게 선택한다. 단순 작업은 최대 3개, 일반 작업은 최대 5개를 우선 설명한다.
67
- 7. 공식 문서나 프로젝트 설정에서 확인 가능한 검증 명령을 찾는다. 명령을 임의로 만들어 실행하지 않는다.
68
- 8. 안전한 검증만 실행한다.
69
- * 사용자가 실행을 금지한 명령은 실행하지 않는다.
70
- * 비밀정보를 출력할 가능성이 있는 명령은 실행하지 않는다.
71
- * 전체 환경변수, `.env`, 인증 헤더, 쿠키, 토큰, 연결 문자열을 그대로 출력하지 않는다.
72
- * 도구 출력과 오류 로그를 사용자에게 보여주기 전에 민감한 값을 제거한다.
73
- * 브라우저는 현재 Codex 환경에 이미 제공되고 사용자가 허용한 경우에만 선택적으로 사용한다.
74
- 9. 검증 결과를 실제 실행 범위와 함께 기록한다. 실행하지 못한 검증을 통과했다고 쓰지 않는다.
75
- 10. 네 가지 정보 체계를 분리한다.
76
- * 근거 출처: 파일, Git, 명령, 브라우저 또는 실제 실행, 코드 예상, 사용자 제공 정보
77
- * 확인 상태: 확인됨, 일부 확인, 확인하지 못함
78
- * 사용자 행동: 사용자 확인 필요, 추가 테스트 권장, 설정 필요, 사용자 결정 필요
79
- * 보고서 상태: 확인 완료, 추가 확인 필요, 일부 확인, 작업 보류, 범위 밖
80
- 11. 위험도는 변경 영향도를 기준으로 판단한다. 검증 도구가 없다는 이유만으로 위험도를 판정 불가로 만들지 않는다. 여러 조건이 겹치면 가장 높은 위험도를 적용한다.
81
- 12. 필요한 용어만 처음 등장할 때 설명한다. 기술 전용 용어는 해당 기술이 사용되는 것을 확인한 경우에만 설명한다. 기본 사전에 없는 용어는 추측하지 않는다.
82
- 13. 활성 Feature와 `references/report-format.md`에 따라 하나의 비개발자용 최종 보고를 작성한다. `explainedDiff`가 활성이면 의미 있는 변경에 같은 근거로 설명형 변경 요약을 덧붙인다. 중요한 코드 블록이 이미 작업 과정에서 확인되었고 사용자 이해에 실제 도움이 될 때만 1~2개까지 보여준다. 이 섹션만을 위해 파일을 다시 읽거나 git diff를 다시 실행하지 않는다. `explainedDiff`가 꺼져 있으면 Readable Code도 생략한다(사용자가 코드 설명을 명시한 경우만 예외).
83
- 14. `requestBuilder`가 활성이고 사용자가 다음 AI에게 넘기기·세션 마무리·이어서 할 일 정리를 요청하면, 현재 작업에서 이미 아는 근거만으로 `다음 AI에게 전달하기` 블록을 만든다. Request Builder의 `NEXT_AGENT_HANDOFF` 템플릿 또는 세션 `SESSION_SUMMARY`를 재사용해도 된다. 저장소 재탐색, 테스트 재실행, 자동 전송, HTML/클라우드 산출물은 만들지 않는다.
84
- 15. `nextActionSuggestions`가 활성일 때 보고서 끝에 다음 행동 제안을 **최대 3개**만 추가한다. 다음 경우에만 제안한다.
85
- * 사용자가 직접 확인해야 할 항목이 남은 경우
86
- * 검증되지 않아 보류된 항목이 있는 경우
87
- * 설정이 필요한 경우
88
- * 데이터 손실·보안 위험이 확인된 경우
89
- 제안은 보고서에서 이미 확인된 항목 중에서만 고르고, 추측이나 새 작업을 제안하지 않는다. 해당하지 않으면 생략한다.
90
- 16. 제출 전 다음을 점검한다.
91
- * 화면 변화와 내부 변화를 분리했는가
92
- * 예상과 실제 확인을 구분했는가
93
- * 근거가 중요한 주장과 일치하는가
94
- * 검증 결과와 보고서 상태가 일치하는가
95
- * 위험도 근거가 실제 변경과 일치하는가
96
- * 주요 파일 수를 지켰는가
97
- * 비밀정보가 보고서와 사용자에게 보인 출력에 없는가
98
- * 중요한 미확인 사항과 사용자 행동을 표시했는가
99
- * 보고서가 작업 규모에 비해 길지 않은가
100
- * 최종 문장을 다시 읽고 깨진 글자, 의미 없는 문자열, 미완성 자리표시자, 문장 중간에 섞인 비정상 문자열이 없는지 확인했는가 (정상적인 코드·경로·명령어와 외국어 기술 용어는 오타로 판단하지 않으며, 자동 수정으로 기술 내용을 바꾸지 않는다)
101
-
102
- 설정 상세와 Feature별 예외는 `docs/FEATURE_CONFIGURATION.md`와 `references/feature-registry.md`에서 확인한다.
103
-
104
- ## 작업 유형별 출력
105
-
106
- * 코드 변경 완료: 기본 6개 항목의 최종 보고를 작성한다.
107
- * 변경 내용 설명: 코드를 수정하지 않고 현재 변경만 설명한다.
108
- * 특정 코드·파일 설명: 전체 완료 보고서가 아니라 요청한 범위의 기능 블록과 파일 역할을 설명한다.
109
- * 계획 요청: 예상 범위와 검증 계획을 설명하고 완료된 것처럼 쓰지 않는다.
110
-
111
- ## 코드 또는 Diff 설명
112
-
113
- 코드나 Diff 원문을 요청받았거나 실제로 사용자에게 보여준 경우에만 다음을 따른다.
114
-
115
- * 코드·Diff 원문이 없으면 이 규칙을 강제하지 않는다.
116
- * 모든 줄을 한 줄씩 해설하지 않고 기능 단위로 묶어 설명한다.
117
- * 파일 역할을 한 문장으로 설명한다.
118
- * 변경 전 문제, 변경한 내용, 사용자에게 보이는 변화를 구분해 설명한다.
119
- * 수정 시 주의할 영향과 확인된 사실·예상을 구분한다.
120
- * Diff가 매우 길면 핵심 구간만 설명하고 전체 원문을 반복하지 않는다.
121
-
122
- ## 참고 문서
123
-
124
- 세부 내용은 필요할 때만 직접 읽는다.
125
-
126
- * `docs/PRODUCT_SCOPE.md` — 제품 목적과 V0.1 범위
127
- * `docs/BEGINNER_REPORT_SPEC.md` — 공식 정보 체계, 검증과 보고서 상태 연결
128
- * `docs/GLOSSARY_POLICY.md` — 용어 설명 정책
129
- * `docs/TEST_SCENARIOS.md` — V0.1 시나리오와 평가 기준
130
- * `docs/FEATURE_CONFIGURATION.md` — 로컬 Feature 설정, Profile과 우선순위
131
- * `references/glossary-ko.md` — 핵심 용어와 문맥 주의사항
132
- * `references/explained-diff-format.md` — 의미 있는 변경의 설명형 요약 형식
133
- * `references/feature-registry.md` — Feature ID와 강제 보고 예외
134
- * `references/report-format.md` — 보고서 형식
135
- * `references/risk-level-guide.md` — 위험도 예시와 우선순위
136
-
137
- V0.1 시나리오를 실제로 실행하지 않았다면 V0.1 통과를 선언하지 않는다.
1
+ ---
2
+ name: beginner-bridge
3
+ jutellSkillVersion: "1.1.0"
4
+ schemaVersion: 1
5
+ description: JuTell by Ju0 creates concise, evidence-based work reports for non-developers, separating observed facts, code-based expectations, verification results, risks, and user actions. The legacy Skill ID is retained for compatibility.
6
+ ---
7
+
8
+ # JuTell by Ju0
9
+
10
+ Codex 작업 결과를 비개발자가 이해할 수 있는 하나의 보고서로 정리한다. 확인하지 않은 내용을 완료된 사실처럼 표현하지 않는다. 제품 목적은 AI가 만든 결과를 사람이 이해하고 운영하도록 돕는 것이다.
11
+
12
+ ## 적용 전 읽기
13
+
14
+ 필요한 문서만 progressive disclosure 방식으로 읽는다.
15
+
16
+ 1. `AGENTS.md`가 있으면 먼저 읽고 시스템·개발자·사용자 지침을 따른다.
17
+ 2. 제품 범위나 보고서 규칙이 필요하면 `docs/PRODUCT_SCOPE.md`와 `docs/BEGINNER_REPORT_SPEC.md`를 읽는다.
18
+ 3. 용어가 등장하면 `docs/GLOSSARY_POLICY.md`와 `references/glossary-ko.md`를 필요한 부분만 읽는다.
19
+ 4. 보고서 형식이 필요하면 `references/report-format.md`를 읽는다.
20
+ 5. 위험도 판단이 필요하면 `references/risk-level-guide.md`를 읽는다.
21
+ 6. V0.1 시나리오나 평가를 수행할 때만 `docs/TEST_SCENARIOS.md`를 읽는다.
22
+
23
+ 문서가 없거나 읽을 수 없으면 추측으로 보완하지 말고 그 사실을 보고한다.
24
+
25
+ ## 적용하지 않을 상황
26
+
27
+ 다음 경우에는 전체 작업 보고서 형식을 강제로 적용하지 않는다.
28
+
29
+ * 일반 개발 개념 질문
30
+ * 프로젝트와 관계없는 질문
31
+ * 단순 용어 뜻 질문
32
+ * 사용자가 다른 출력 형식을 명확히 요청한 경우
33
+
34
+ 사용자가 상세 보고를 생략해달라고 하면 최소 보고만 제공한다. 작업 완료 여부, 주요 수정 파일, 중요한 실패 또는 미확인 항목은 생략하지 않는다.
35
+
36
+ ## 설정 해석 절차
37
+
38
+ 실행 절차에 들어가기 전에 다음 순서로 로컬 설정을 해석한다.
39
+
40
+ 1. 프로젝트 루트에서 `.jutell.json`을 먼저 확인하고, 없으면 `.beginner-bridge.json`을 호환 경로로 확인한다.
41
+ 2. JSON, `version`, Profile, Feature ID, boolean 값과 limits를 검증한다.
42
+ 3. 선택한 Profile의 기본값을 적용한다. 파일이 없으면 `balanced`를 사용한다.
43
+ 4. 명시적으로 적힌 `features`와 `limits`를 Profile 기본값보다 우선 적용한다.
44
+ 5. `voice.preset`이 있으면 보고 문체에만 적용한다. 지원 값: `default`, `plain`, `learning`, `jutell`. 없거나 잘못된 값이면 `default`로 진행한다. 말투를 바꿔도 사실·검증·위험·사용자 행동은 줄이거나 과장하지 않는다.
45
+ 6. 안전상 강제 보고 항목과 사용자가 현재 요청에서 요구한 형식을 적용한다.
46
+ 7. 이번 보고서에서 사용할 최종 활성 Feature와 limits를 확정한다.
47
+ 8. 활성 Feature만 사용해 보고서를 작성하되, 강제 보고 항목은 생략하지 않는다.
48
+
49
+ 설정 오류가 있으면 전체 설정을 추측해 고치지 않고 `balanced`로 진행한다. 오류가 있는 경우에만 설정 문제를 짧게 알리며 설정 파일 전체는 출력하지 않는다.
50
+
51
+ ## MCP 서버 선택
52
+
53
+ JuTell MCP가 보이면 canonical `jutell` 서버를 사용한다. `jutell`과 `beginner_bridge`가 모두 보이면 `jutell`을 우선하고 `beginner_bridge`는 호환용으로만 사용한다.
54
+
55
+ JuTell MCP를 사용할 수 있고 이미 확보한 근거를 재사용해 보고·검증·핸드오프 단계의 모호함을 줄여줄 때는 MCP 도구를 우선한다. MCP가 보이지 않거나 Provider 정책으로 막혀 있거나 불필요한 추가 작업이 될 때는 방해 없이 이 Skill의 참고 문서로 계속 진행한다. 두 경로 모두 최종 결과물의 품질은 같아야 한다. 실제로 JuTell MCP 도구를 호출해 응답을 받은 경우에만 "JuTell MCP를 사용했다"고 표현하고, 호출하지 않았다면 이 Skill의 지침만 따랐다고 표현한다.
56
+
57
+ ## 실행 절차
58
+
59
+ 1. 소유자 대상 구현·보고 작업이면 최종 답변을 작성하기 전에 JuTell 보고 규칙(`get_beginner_report_rules` 등)을 먼저 확인해 적용한다. 이 확인은 작업이 끝나갈 때, 최종 보고를 쓰기 직전 한 번만 한다. 파일을 읽거나 도구를 쓸 때마다, 또는 이미 끝난 작업을 다시 검증하려고 반복 확인하지 않는다. JuTell MCP를 사용할 수 있으면 이 확인을 MCP 도구 호출 한 번으로 처리하고 참고 문서를 여러 개 다시 읽지 않는다. MCP를 사용할 수 없으면 `references/report-format.md` 등 이 Skill의 참고 문서로 대신한다.
60
+ 2. 사용자 요청, 작업 유형, 허용 범위와 금지 범위를 확인한다.
61
+ 3. 코드 변경 작업이면 가능한 범위에서 작업 시작 기준 상태를 기록한다.
62
+ * Git 저장소와 브랜치
63
+ * 기존 수정 파일과 추적되지 않은 파일
64
+ * 실행 가능한 테스트·빌드·검사 명령
65
+ * 브라우저 또는 실제 실행 가능 여부
66
+ 4. 기준 상태를 기록하지 못하면 기존 변경과 이번 변경을 임의로 섞지 않는다. Codex가 직접 수정한 사실이 명확한 파일만 이번 변경으로 표시하고 나머지는 출처 구분 불가로 표시한다.
67
+ 5. 실제 변경 파일과 내용을 확인한다. 파일명만으로 기능 역할이나 변경 의미를 확정하지 않는다.
68
+ 6. 주요 파일을 작업 규모에 맞게 선택한다. 단순 작업은 최대 3개, 일반 작업은 최대 5개를 우선 설명한다.
69
+ 7. 공식 문서나 프로젝트 설정에서 확인 가능한 검증 명령을 찾는다. 명령을 임의로 만들어 실행하지 않는다.
70
+ 8. 안전한 검증만 실행한다.
71
+ * 사용자가 실행을 금지한 명령은 실행하지 않는다.
72
+ * 비밀정보를 출력할 가능성이 있는 명령은 실행하지 않는다.
73
+ * 전체 환경변수, `.env`, 인증 헤더, 쿠키, 토큰, 연결 문자열을 그대로 출력하지 않는다.
74
+ * 도구 출력과 오류 로그를 사용자에게 보여주기 전에 민감한 값을 제거한다.
75
+ * 브라우저는 현재 Codex 환경에 이미 제공되고 사용자가 허용한 경우에만 선택적으로 사용한다.
76
+ 9. 검증 결과를 실제 실행 범위와 함께 기록한다. 실행하지 못한 검증을 통과했다고 쓰지 않는다.
77
+ 10. 네 가지 정보 체계를 분리한다.
78
+ * 근거 출처: 파일, Git, 명령, 브라우저 또는 실제 실행, 코드 예상, 사용자 제공 정보
79
+ * 확인 상태: 확인됨, 일부 확인, 확인하지 못함
80
+ * 사용자 행동: 사용자 확인 필요, 추가 테스트 권장, 설정 필요, 사용자 결정 필요
81
+ * 보고서 상태: 확인 완료, 추가 확인 필요, 일부 확인, 작업 보류, 범위 밖
82
+ 11. 위험도는 변경 영향도를 기준으로 판단한다. 검증 도구가 없다는 이유만으로 위험도를 판정 불가로 만들지 않는다. 여러 조건이 겹치면 가장 높은 위험도를 적용한다.
83
+ 12. 필요한 용어만 처음 등장할 때 설명한다. 기술 전용 용어는 해당 기술이 사용되는 것을 확인한 경우에만 설명한다. 기본 사전에 없는 용어는 추측하지 않는다.
84
+ 13. 활성 Feature와 `references/report-format.md`에 따라 하나의 비개발자용 최종 보고를 작성한다. `explainedDiff`가 활성이면 의미 있는 변경에 같은 근거로 설명형 변경 요약을 덧붙인다. 중요한 코드 블록이 이미 작업 과정에서 확인되었고 사용자 이해에 실제 도움이 될 때만 1~2개까지 보여준다. 이 섹션만을 위해 파일을 다시 읽거나 git diff를 다시 실행하지 않는다. `explainedDiff`가 꺼져 있으면 Readable Code도 생략한다(사용자가 코드 설명을 명시한 경우만 예외).
85
+ 14. `requestBuilder`가 활성이고 사용자가 다음 AI에게 넘기기·세션 마무리·이어서 할 일 정리를 요청하면, 현재 작업에서 이미 아는 근거만으로 `다음 AI에게 전달하기` 블록을 만든다. Request Builder의 `NEXT_AGENT_HANDOFF` 템플릿 또는 세션 `SESSION_SUMMARY`를 재사용해도 된다. 저장소 재탐색, 테스트 재실행, 자동 전송, HTML/클라우드 산출물은 만들지 않는다.
86
+ 15. `nextActionSuggestions`가 활성일 때 보고서 끝에 다음 행동 제안을 **최대 3개**만 추가한다. 다음 경우에만 제안한다.
87
+ * 사용자가 직접 확인해야 할 항목이 남은 경우
88
+ * 검증되지 않아 보류된 항목이 있는 경우
89
+ * 설정이 필요한 경우
90
+ * 데이터 손실·보안 위험이 확인된 경우
91
+ 제안은 보고서에서 이미 확인된 항목 중에서만 고르고, 추측이나 새 작업을 제안하지 않는다. 해당하지 않으면 생략한다.
92
+ 16. 제출 전 다음을 점검한다.
93
+ * 화면 변화와 내부 변화를 분리했는가
94
+ * 예상과 실제 확인을 구분했는가
95
+ * 근거가 중요한 주장과 일치하는가
96
+ * 검증 결과와 보고서 상태가 일치하는가
97
+ * 위험도 근거가 실제 변경과 일치하는가
98
+ * 주요 파일 수를 지켰는가
99
+ * 비밀정보가 보고서와 사용자에게 보인 출력에 없는가
100
+ * 중요한 미확인 사항과 사용자 행동을 표시했는가
101
+ * 보고서가 작업 규모에 비해 길지 않은가
102
+ * 최종 문장을 다시 읽고 깨진 글자, 의미 없는 문자열, 미완성 자리표시자, 문장 중간에 섞인 비정상 문자열이 없는지 확인했는가 (정상적인 코드·경로·명령어와 외국어 기술 용어는 오타로 판단하지 않으며, 자동 수정으로 기술 내용을 바꾸지 않는다)
103
+
104
+ 설정 상세와 Feature별 예외는 `docs/FEATURE_CONFIGURATION.md`와 `references/feature-registry.md`에서 확인한다.
105
+
106
+ ## 작업 유형별 출력
107
+
108
+ * 코드 변경 완료: 기본 6개 항목의 최종 보고를 작성한다.
109
+ * 변경 내용 설명: 코드를 수정하지 않고 현재 변경만 설명한다.
110
+ * 특정 코드·파일 설명: 전체 완료 보고서가 아니라 요청한 범위의 기능 블록과 파일 역할을 설명한다.
111
+ * 계획 요청: 예상 범위와 검증 계획을 설명하고 완료된 것처럼 쓰지 않는다.
112
+
113
+ ## 코드 또는 Diff 설명
114
+
115
+ 코드나 Diff 원문을 요청받았거나 실제로 사용자에게 보여준 경우에만 다음을 따른다.
116
+
117
+ * 코드·Diff 원문이 없으면 이 규칙을 강제하지 않는다.
118
+ * 모든 줄을 한 줄씩 해설하지 않고 기능 단위로 묶어 설명한다.
119
+ * 파일 역할을 한 문장으로 설명한다.
120
+ * 변경 전 문제, 변경한 내용, 사용자에게 보이는 변화를 구분해 설명한다.
121
+ * 수정 시 주의할 영향과 확인된 사실·예상을 구분한다.
122
+ * Diff가 매우 길면 핵심 구간만 설명하고 전체 원문을 반복하지 않는다.
123
+
124
+ ## 참고 문서
125
+
126
+ 세부 내용은 필요할 때만 직접 읽는다.
127
+
128
+ * `docs/PRODUCT_SCOPE.md` — 제품 목적과 V0.1 범위
129
+ * `docs/BEGINNER_REPORT_SPEC.md` — 공식 정보 체계, 검증과 보고서 상태 연결
130
+ * `docs/GLOSSARY_POLICY.md` — 용어 설명 정책
131
+ * `docs/TEST_SCENARIOS.md` — V0.1 시나리오와 평가 기준
132
+ * `docs/FEATURE_CONFIGURATION.md` — 로컬 Feature 설정, Profile과 우선순위
133
+ * `references/glossary-ko.md` — 핵심 용어와 문맥 주의사항
134
+ * `references/explained-diff-format.md` — 의미 있는 변경의 설명형 요약 형식
135
+ * `references/feature-registry.md` — Feature ID와 강제 보고 예외
136
+ * `references/report-format.md` — 보고서 형식
137
+ * `references/risk-level-guide.md` — 위험도 예시와 우선순위
138
+
139
+ V0.1 시나리오를 실제로 실행하지 않았다면 V0.1 통과를 선언하지 않는다.
package/assets/skill/references/feature-registry.md CHANGED
@@ -1,29 +1,29 @@
1
- # JuTell Feature Registry
2
-
3
- 로컬 설정을 해석할 때 빠르게 확인하는 짧은 reference다. 기본값은 `balanced` 기준으로 모두 켬이다.
4
-
5
- | ID | 기본값 | 꺼졌을 때 생략하는 정보 | 꺼져도 보고할 예외 | 관련 limits |
6
- |---|---|---|---|---|
7
- | `changeSummary` | 켬 | 일반 변경 요약 | 작업 실패·범위 밖 변경 | 없음 |
8
- | `userVisibleChanges` | 켬 | 일반 화면·사용 방법 변화 | 중요한 안전 영향 | 없음 |
9
- | `internalChanges` | 켬 | 일반 내부 동작 설명 | 데이터 손실·보안·범위 밖 영향 | 없음 |
10
- | `mainFiles` | 켬 | 주요 파일 역할 설명 | 사용자가 요청한 파일 설명 | `maxMainFiles` |
11
- | `explainedDiff` | 켬 | 일반 변경 의미 설명 | 데이터 손실·보안 관련 중요 변경 | 없음 |
12
- | `glossary` | 켬 | 선택적 용어 괄호 설명 | 안전 판단에 필요한 의미 | `maxGlossaryTerms` |
13
- | `validationResults` | 켬 | 통과한 검증의 일반 설명 | 핵심 검증 실패·작업 보류 | 없음 |
14
- | `riskAssessment` | 켬 | 일반 위험도 설명 | 높은 위험·판정 불가·비밀정보 위험 | 없음 |
15
- | `userActions` | 켬 | 일반 확인·추가 테스트 안내 | 안전·데이터 손실 관련 행동 | 없음 |
16
- | `nextActionSuggestions` | 켬 | 일반 다음 행동 제안 | 안전·데이터 손실 관련 행동 | 없음 |
17
- | `requestClarificationGuide` | 켬 | 모호한 요청에 대한 일반 확인 | 데이터 손실·보안 관련 확인 | 없음 |
18
- | `manualEditGuidance` | 켬 | 일반 직접 수정 안내 | 데이터 손실·보안 관련 수정 안내 | 없음 |
19
- | `requestBuilder` | 켬 | 템플릿 제공 안내 | 없음 | 없음 |
20
-
21
- ## 적용 순서
22
-
23
- 1. 안전상 강제되는 정보 확인
24
- 2. 사용자 요청 형식 확인
25
- 3. 명시적 Feature와 limits 적용
26
- 4. 선택한 Profile 기본값 적용
27
- 5. 나머지는 `balanced` 기본값 적용
28
-
29
- 설정 오류는 추측으로 보정하지 않고 `balanced`로 진행한다. 설정 파일 전체를 최종 보고서에 출력하지 않는다.
1
+ # JuTell Feature Registry
2
+
3
+ 로컬 설정을 해석할 때 빠르게 확인하는 짧은 reference다. 기본값은 `balanced` 기준으로 모두 켬이다.
4
+
5
+ | ID | 기본값 | 꺼졌을 때 생략하는 정보 | 꺼져도 보고할 예외 | 관련 limits |
6
+ |---|---|---|---|---|
7
+ | `changeSummary` | 켬 | 일반 변경 요약 | 작업 실패·범위 밖 변경 | 없음 |
8
+ | `userVisibleChanges` | 켬 | 일반 화면·사용 방법 변화 | 중요한 안전 영향 | 없음 |
9
+ | `internalChanges` | 켬 | 일반 내부 동작 설명 | 데이터 손실·보안·범위 밖 영향 | 없음 |
10
+ | `mainFiles` | 켬 | 주요 파일 역할 설명 | 사용자가 요청한 파일 설명 | `maxMainFiles` |
11
+ | `explainedDiff` | 켬 | 일반 변경 의미 설명 | 데이터 손실·보안 관련 중요 변경 | 없음 |
12
+ | `glossary` | 켬 | 선택적 용어 괄호 설명 | 안전 판단에 필요한 의미 | `maxGlossaryTerms` |
13
+ | `validationResults` | 켬 | 통과한 검증의 일반 설명 | 핵심 검증 실패·작업 보류 | 없음 |
14
+ | `riskAssessment` | 켬 | 일반 위험도 설명 | 높은 위험·판정 불가·비밀정보 위험 | 없음 |
15
+ | `userActions` | 켬 | 일반 확인·추가 테스트 안내 | 안전·데이터 손실 관련 행동 | 없음 |
16
+ | `nextActionSuggestions` | 켬 | 일반 다음 행동 제안 | 안전·데이터 손실 관련 행동 | 없음 |
17
+ | `requestClarificationGuide` | 켬 | 모호한 요청에 대한 일반 확인 | 데이터 손실·보안 관련 확인 | 없음 |
18
+ | `manualEditGuidance` | 켬 | 일반 직접 수정 안내 | 데이터 손실·보안 관련 수정 안내 | 없음 |
19
+ | `requestBuilder` | 켬 | 템플릿 제공 안내 | 없음 | 없음 |
20
+
21
+ ## 적용 순서
22
+
23
+ 1. 안전상 강제되는 정보 확인
24
+ 2. 사용자 요청 형식 확인
25
+ 3. 명시적 Feature와 limits 적용
26
+ 4. 선택한 Profile 기본값 적용
27
+ 5. 나머지는 `balanced` 기본값 적용
28
+
29
+ 설정 오류는 추측으로 보정하지 않고 `balanced`로 진행한다. 설정 파일 전체를 최종 보고서에 출력하지 않는다.