From 275eaa65390c07f85009687f48e63eab0b2aeb9e Mon Sep 17 00:00:00 2001 From: hun99999 <48903443+hun99999@users.noreply.github.com> Date: Tue, 9 Jun 2026 08:10:55 +0900 Subject: [PATCH] docs: add target repo Claude prompt to readmes --- README.ja.md | 50 +++++++++++++++++++++++++++++++++ README.ko.md | 50 +++++++++++++++++++++++++++++++++ README.md | 50 +++++++++++++++++++++++++++++++++ README.zh-CN.md | 50 +++++++++++++++++++++++++++++++++ tests/test_readme_docs.py | 59 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 259 insertions(+) diff --git a/README.ja.md b/README.ja.md index 5125649..db4288b 100644 --- a/README.ja.md +++ b/README.ja.md @@ -48,6 +48,56 @@ Codex、Claude Code、OpenCode向けのプロセス重視AIコーディング環 - credential、private MCP endpoint、個人パス、マシン固有の trust state を public baseline に含めないよう設計されています。 - 英語、韓国語、日本語、中国語簡体字の文書を同じレポで提供します。 +## 対象プロジェクト用 Claude Code プロンプト + +Claude Code を対象プロジェクトのリポジトリ内で開き、次をそのまま貼り付けます。公開 URL を参照するため、個人ローカルパスに依存しません。 + +```text +このプロジェクトに agent-bootstrap ベースの vibe-coding guardrails を適用してください。 + +参照リポジトリ: +- https://github.com/hun99999/agent-bootstrap + +まずこのプロジェクトで git status --short --branch を実行してください。未コミット変更または untracked files がある場合は停止し、どう扱うか私に確認してください。承認なしに stash、delete、overwrite、git add をしないでください。 + +次にこのプロジェクトを調査してください: +- AGENTS.md、CLAUDE.md、README.md、既存 docs +- package.json、pyproject.toml、Cargo.toml、go.mod、または他の言語/ツールの手がかり +- 実際の test、lint、type-check、build コマンド +- source-of-truth helper、type、schema、public API、module boundary、dependency direction、error boundary、re-export/barrel policy、known hotspot + +上の参照リポジトリ URL の文書を読んでください。必要ならこのプロジェクト外に read-only clone して読んでください。次のファイルを source として使ってください: +- docs/agent-setup-playbook.md +- docs/vibe-coding-guardrails.md +- docs/global-guardrail-setup.md +- docs/local-project-knowledge-template.md +- prompts/apply-vibe-coding-guardrails.md +- prompts/start-with-vibe-coding-guardrails.md + +可能なら optional tool inventory を read-only evidence としてだけ実行してください。参照リポジトリを clone した場合は、その clone の script をこのプロジェクト root に対して実行してください: +- python3 /scripts/inventory_optional_tools.py --repo-root . +- python3 /scripts/inventory_optional_tools.py --repo-root . --json + +その script がローカルで使えない場合は、その制約を説明し、直接調査で続けてください。任意ツールを自動インストールしないでください。Obsidian、Lumin Repo Lens、dependency lint、strict type checks、cycle detection、complexity limits は、インストール承認を求める前に required、recommended、optional、skipped のいずれかに分類してください。 + +このプロジェクトに必要な最小限の guardrail だけを適用してください: +- このプロジェクトがすでに使っている agent guidance を追加または更新する +- docs/local-project-knowledge-template.md をもとに project structure index を作る +- source-of-truth helper、type、schema、public API、module boundary、dependency direction、error boundary、re-export policy、test strategy、known hotspot、decision を記録する +- local evidence artifact が作られる可能性がある場合だけ .audit/ を .gitignore に追加する +- personal vault path、private path、credential、MCP endpoint、auth state、browser profile、machine-specific trust setting をコミットしない + +このプロジェクトが TS/JS-heavy で、私が Lumin Repo Lens の使用を承認した場合だけ evidence tool として使ってください: +- structural claim には evidence が必要 +- absence claim には scan range が必要 +- 証拠が部分的な場合は "not observed in this scan range" と言う +- pre-write intent は names、shapes、files、dependencies、plannedTypeEscapes を使う +- post-write machine evidence は type escapes、unexpected files、scan range、confidence changes に限定する +- duplicate helpers、dependency drift、public API drift、re-export drift は direct evidence が必要な manual review claim とする + +振る舞いの変更には TDD を使ってください。変更後、このプロジェクトの実際の verification コマンドと post-write review を実行してください。変更ファイル、実行コマンド、検証結果、skipped/recommended optional tools、残リスクを報告してください。 +``` + ## クイックスタート 最初にスコープを選ぶことが重要です。エージェントのセットアップは、新しいハーネス、プラグイン、provider、リポジトリ運用を一度に変えようとすると失敗しやすくなります。まず最小の有効範囲を適用し、検証してから広げます。 diff --git a/README.ko.md b/README.ko.md index a85d687..bea6585 100644 --- a/README.ko.md +++ b/README.ko.md @@ -60,6 +60,56 @@ Codex, Claude Code, OpenCode를 위한 프로세스 중심 AI 코딩 환경 부 선택 도구는 판단 후 사용합니다. Obsidian, Lumin Repo Lens, dependency lint, cycle detection, strict type checks, complexity limits는 대상 레포와 사용자 승인으로 필요성이 확인될 때만 추천하거나 설치합니다. +## 대상 프로젝트용 Claude Code 프롬프트 + +Claude Code를 대상 프로젝트 레포 안에서 연 뒤 아래 프롬프트를 그대로 붙여넣습니다. 공개 URL을 참조하므로 개인 로컬 경로에 의존하지 않습니다. + +```text +이 프로젝트에 agent-bootstrap 기반 vibe-coding guardrails를 적용해줘. + +참조 레포: +- https://github.com/hun99999/agent-bootstrap + +먼저 이 프로젝트에서 git status --short --branch 를 실행해라. uncommitted changes 또는 untracked files가 있으면 멈추고 나에게 처리 방식을 물어봐라. 승인 없이 stash, delete, overwrite, git add를 하지 마라. + +그 다음 이 프로젝트를 조사해라: +- AGENTS.md, CLAUDE.md, README.md, 기존 docs +- package.json, pyproject.toml, Cargo.toml, go.mod 또는 다른 언어/도구 신호 +- 실제 test, lint, type-check, build 명령 +- source-of-truth helper, type, schema, public API, module boundary, dependency direction, error boundary, re-export/barrel policy, known hotspot + +위 참조 레포 URL의 문서를 읽어라. 필요하면 이 프로젝트 밖에 read-only로 clone해서 읽어라. 다음 파일을 source로 사용해라: +- docs/agent-setup-playbook.md +- docs/vibe-coding-guardrails.md +- docs/global-guardrail-setup.md +- docs/local-project-knowledge-template.md +- prompts/apply-vibe-coding-guardrails.md +- prompts/start-with-vibe-coding-guardrails.md + +가능하면 optional tool inventory를 read-only evidence로만 실행해라. 참조 레포를 clone했다면 그 clone의 script를 이 프로젝트 root에 대해 실행해라: +- python3 /scripts/inventory_optional_tools.py --repo-root . +- python3 /scripts/inventory_optional_tools.py --repo-root . --json + +그 script를 로컬에서 쓸 수 없다면 그 한계를 말하고 직접 조사로 계속해라. 선택 도구를 자동 설치하지 마라. Obsidian, Lumin Repo Lens, dependency lint, strict type checks, cycle detection, complexity limits는 설치 승인 요청 전에 required, recommended, optional, skipped 중 하나로 분류해라. + +이 프로젝트에 필요한 최소 guardrail만 적용해라: +- 이 프로젝트가 이미 쓰는 agent guidance를 추가하거나 업데이트한다 +- docs/local-project-knowledge-template.md를 바탕으로 프로젝트 구조 인덱스를 만든다 +- source-of-truth helper, type, schema, public API, module boundary, dependency direction, error boundary, re-export policy, test strategy, known hotspot, decision을 기록한다 +- local evidence artifact가 생길 수 있을 때만 .audit/를 .gitignore에 추가한다 +- personal vault path, private path, credential, MCP endpoint, auth state, browser profile, machine-specific trust setting을 커밋하지 않는다 + +이 프로젝트가 TS/JS-heavy이고 내가 Lumin Repo Lens 사용을 승인한 경우에만 evidence tool로 사용해라: +- structural claim에는 evidence가 필요하다 +- absence claim에는 scan range가 필요하다 +- 증거가 부분적이면 "not observed in this scan range"라고 말해라 +- pre-write intent는 names, shapes, files, dependencies, plannedTypeEscapes를 사용한다 +- post-write machine evidence는 type escapes, unexpected files, scan range, confidence changes로만 제한한다 +- duplicate helpers, dependency drift, public API drift, re-export drift는 direct evidence가 필요한 manual review claim이다 + +행동 변경에는 TDD를 사용해라. 변경 후 이 프로젝트의 실제 verification 명령과 post-write review를 실행해라. 변경 파일, 실행 명령, 검증 결과, skipped/recommended optional tools, 남은 리스크를 보고해라. +``` + ## 빠른 시작 먼저 범위를 고릅니다. 에이전트 세팅 실패는 보통 한 번에 너무 많이 하려 할 때 생깁니다. 새 하네스, 새 플러그인, 새 provider, 레포 워크플로우를 동시에 바꾸지 말고, 가장 작은 유효 범위를 먼저 적용하고 검증한 뒤 넓힙니다. diff --git a/README.md b/README.md index 9ddd98d..036a067 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,56 @@ Use this repository as an operating guide, not only as an installer. Optional tooling is decision-based. Obsidian, Lumin Repo Lens, dependency lint, cycle detection, strict type checks, and complexity limits should be recommended or installed only when the target repository and user approval justify them. +## Target Repository Claude Code Prompt + +Paste this into Claude Code while Claude Code is open inside the target project repository. It tells the agent to use this public repository as the guardrail source without relying on a private local path. + +```text +Apply agent-bootstrap vibe-coding guardrails to this project. + +Reference repository: +- https://github.com/hun99999/agent-bootstrap + +First, run git status --short --branch in this project. If there are uncommitted changes or untracked files, stop and ask me how to handle them. Do not stash, delete, overwrite, or git add anything without approval. + +Then inspect this project: +- AGENTS.md, CLAUDE.md, README.md, and existing docs +- package.json, pyproject.toml, Cargo.toml, go.mod, or other language/tooling signals +- real test, lint, type-check, and build commands +- source-of-truth helpers, types, schemas, public APIs, module boundaries, dependency direction, error boundaries, re-export or barrel policy, and known hotspots + +Read the reference repository docs from the URL above. If needed, clone it read-only outside this project. Use these files as the source: +- docs/agent-setup-playbook.md +- docs/vibe-coding-guardrails.md +- docs/global-guardrail-setup.md +- docs/local-project-knowledge-template.md +- prompts/apply-vibe-coding-guardrails.md +- prompts/start-with-vibe-coding-guardrails.md + +Run optional tool inventory only as read-only evidence when possible. If you cloned the reference repository, run its script against this project root: +- python3 /scripts/inventory_optional_tools.py --repo-root . +- python3 /scripts/inventory_optional_tools.py --repo-root . --json + +If that script is not available locally, explain the limitation and continue with direct inspection. Do not install optional tools automatically. Classify Obsidian, Lumin Repo Lens, dependency lint, strict type checks, cycle detection, and complexity limits as required, recommended, optional, or skipped before asking for any install approval. + +Apply only the smallest useful guardrails for this project: +- add or update the project agent guidance that this project already uses +- create a project structure index from docs/local-project-knowledge-template.md +- record source-of-truth helpers, types, schemas, public APIs, module boundaries, dependency direction, error boundaries, re-export policy, test strategy, known hotspots, and decisions +- add .audit/ to .gitignore only if local evidence artifacts may be produced +- do not commit personal vault paths, private paths, credentials, MCP endpoints, auth state, browser profiles, or machine-specific trust settings + +If this is a TS/JS-heavy project and I approve Lumin Repo Lens, use it only as an evidence tool: +- structural claims require evidence +- absence claims require scan range +- say "not observed in this scan range" when evidence is partial +- pre-write intent uses names, shapes, files, dependencies, plannedTypeEscapes +- post-write machine evidence is limited to type escapes, unexpected files, scan range, and confidence changes +- duplicate helpers, dependency drift, public API drift, and re-export drift are manual review claims that need direct evidence + +Use TDD for behavior changes. After changes, run this project's real verification commands and post-write review. Report files changed, commands run, verification results, optional tools skipped or recommended, and remaining risks. +``` + ## Quick Start Choose the scope first. Most failed agent setup work starts by configuring too much: a new harness, a new plugin stack, a new provider path, and a repo workflow all at once. Start with the smallest useful scope, verify it, then expand. diff --git a/README.zh-CN.md b/README.zh-CN.md index b6fa1c9..6056d02 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -48,6 +48,56 @@ - 设计目标就是不把 credential、private MCP endpoint、个人路径或机器特定 trust state 放进 public baseline。 - 同一个仓库同时提供英文、韩文、日文、简体中文文档。 +## 目标项目 Claude Code 提示词 + +在目标项目仓库中打开 Claude Code，然后原样粘贴下面的提示词。它引用公开 URL，不依赖个人本地路径。 + +```text +请把 agent-bootstrap 的 vibe-coding guardrails 应用到这个项目。 + +参考仓库: +- https://github.com/hun99999/agent-bootstrap + +首先在这个项目中运行 git status --short --branch。如果有未提交修改或 untracked files，停止并询问我如何处理。未经批准，不要 stash、delete、overwrite 或 git add。 + +然后检查这个项目: +- AGENTS.md、CLAUDE.md、README.md 和现有 docs +- package.json、pyproject.toml、Cargo.toml、go.mod 或其他语言/工具信号 +- 真实的 test、lint、type-check、build 命令 +- source-of-truth helper、type、schema、public API、module boundary、dependency direction、error boundary、re-export/barrel policy、known hotspot + +阅读上面参考仓库 URL 中的文档。必要时，在这个项目之外 read-only clone 后阅读。使用这些文件作为 source: +- docs/agent-setup-playbook.md +- docs/vibe-coding-guardrails.md +- docs/global-guardrail-setup.md +- docs/local-project-knowledge-template.md +- prompts/apply-vibe-coding-guardrails.md +- prompts/start-with-vibe-coding-guardrails.md + +如果可以，把 optional tool inventory 只作为 read-only evidence 运行。如果已经 clone 参考仓库，就用那个 clone 的 script 检查这个项目 root: +- python3 /scripts/inventory_optional_tools.py --repo-root . +- python3 /scripts/inventory_optional_tools.py --repo-root . --json + +如果这个 script 在本地不可用，说明限制，并继续直接检查。不要自动安装可选工具。Obsidian、Lumin Repo Lens、dependency lint、strict type checks、cycle detection、complexity limits 在请求安装批准前，必须先分类为 required、recommended、optional 或 skipped。 + +只应用这个项目需要的最小 guardrail: +- 添加或更新这个项目已经使用的 agent guidance +- 基于 docs/local-project-knowledge-template.md 创建 project structure index +- 记录 source-of-truth helper、type、schema、public API、module boundary、dependency direction、error boundary、re-export policy、test strategy、known hotspot 和 decision +- 只有在可能产生 local evidence artifact 时，才把 .audit/ 加入 .gitignore +- 不要提交 personal vault path、private path、credential、MCP endpoint、auth state、browser profile 或 machine-specific trust setting + +只有当这个项目是 TS/JS-heavy，并且我批准使用 Lumin Repo Lens 时，才把它作为 evidence tool 使用: +- structural claim 需要 evidence +- absence claim 需要 scan range +- 证据不完整时，说 "not observed in this scan range" +- pre-write intent 使用 names、shapes、files、dependencies、plannedTypeEscapes +- post-write machine evidence 仅限 type escapes、unexpected files、scan range、confidence changes +- duplicate helpers、dependency drift、public API drift、re-export drift 是需要 direct evidence 的 manual review claim + +行为变更使用 TDD。修改后运行这个项目真实的 verification 命令和 post-write review。报告修改文件、执行命令、验证结果、skipped/recommended optional tools 和剩余风险。 +``` + ## 快速开始 先选择范围。代理设置最容易失败的情况，是一次性改动新的 harness、新插件栈、新 provider 和仓库工作流。先应用最小的有效范围，验证之后再扩大。 diff --git a/tests/test_readme_docs.py b/tests/test_readme_docs.py index 6531e4a..1ee5450 100644 --- a/tests/test_readme_docs.py +++ b/tests/test_readme_docs.py @@ -87,6 +87,65 @@ def test_readme_explains_guardrail_workflows_near_the_top(self) -> None: for phrase in expected_phrases: self.assertIn(phrase, introduction) + def test_all_readmes_include_public_target_repo_claude_prompt(self) -> None: + expectations = { + "README.md": ( + "Target Repository Claude Code Prompt", + "Reference repository:", + "https://github.com/hun99999/agent-bootstrap", + "Apply agent-bootstrap vibe-coding guardrails to this project.", + "git status --short --branch", + "optional tool inventory", + "Obsidian", + "Lumin Repo Lens", + "scan range", + "Do not install optional tools automatically", + ), + "README.ko.md": ( + "대상 프로젝트용 Claude Code 프롬프트", + "참조 레포:", + "https://github.com/hun99999/agent-bootstrap", + "이 프로젝트에 agent-bootstrap 기반 vibe-coding guardrails를 적용해줘.", + "git status --short --branch", + "optional tool inventory", + "Obsidian", + "Lumin Repo Lens", + "scan range", + "선택 도구를 자동 설치하지 마라", + ), + "README.ja.md": ( + "対象プロジェクト用 Claude Code プロンプト", + "参照リポジトリ:", + "https://github.com/hun99999/agent-bootstrap", + "このプロジェクトに agent-bootstrap ベースの vibe-coding guardrails を適用してください。", + "git status --short --branch", + "optional tool inventory", + "Obsidian", + "Lumin Repo Lens", + "scan range", + "任意ツールを自動インストールしない", + ), + "README.zh-CN.md": ( + "目标项目 Claude Code 提示词", + "参考仓库:", + "https://github.com/hun99999/agent-bootstrap", + "请把 agent-bootstrap 的 vibe-coding guardrails 应用到这个项目。", + "git status --short --branch", + "optional tool inventory", + "Obsidian", + "Lumin Repo Lens", + "scan range", + "不要自动安装可选工具", + ), + } + + for relative, phrases in expectations.items(): + with self.subTest(relative=relative): + readme = (REPO_ROOT / relative).read_text(encoding="utf-8") + for phrase in phrases: + self.assertIn(phrase, readme) + self.assertNotIn("/" + "Users/hooooonje/codex-dotfiles", readme) + def test_korean_readme_explains_guardrail_workflows_near_the_top(self) -> None: readme = (REPO_ROOT / "README.ko.md").read_text(encoding="utf-8") introduction = readme[:7000]