Communitygithub.com

ASoudy/AGS

當從前沿AI收到詳細的實作計畫時,在 OpenCode 中使用非前沿程式碼模型來執行。它會根據實際的儲存庫驗證計畫,將其分解為安全的步驟,驗證每個步驟,檢查差異,並防止破壞性變更。觸發條件:收到來自 Claude Opus/GPT-5 等的多步驟計畫、執行預先撰寫的規格、實作詳細的 PR 描述,或被告知「逐步執行此計畫」。

AGS 是什麼?

此技能旨在安全地執行由前沿 AI(如 Claude Opus 或 GPT-5)產生的詳細、多步驟實作計畫,特別是在使用能力較弱的非前沿程式碼模型時。它認識到前沿計畫雖是強有力的假設,但絕非絕對真理,往往會因不存在的檔案、虛構的匯入或不相容的架構而與實際儲存庫不一致。因此,核心工作流程包含一個嚴格的驗證循環:首先建立儲存庫基準線,並將每個計畫步驟與實際程式碼進行比對;然後一次執行一個步驟,並緊接進行最小可行驗證(如針對性 lint 或類型檢查);最後檢查 Git 差異,以確保變更範圍受到嚴格限制。對於未提交的變更和自動提交,它也有嚴格的準則,以防止意外破壞。如果某個步驟反覆驗證失敗,技能會強制停止盲目修補,要求代理程式仔細分析錯誤、提出新的假設,並酌情縮小範圍或明確報告阻礙。此技能主要設計用於 Cline、Codex 或 OpenCode 等平台,透過將高風險、多步驟的計畫轉化為可管理、經過驗證且易於審查的增量變更,最大限度地減少引入重大問題或浪費時間進行無效嘗試的可能性。

相容平台✓Claude Code~Codex CLI~Cursor✓Gemini CLI✓OpenCode
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/claude_skills_libraries/landing-page-mastery/skills/frontier-plan-opencode-executor

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Frontier Plan OpenCode Executor

核心原則

前沿計畫是一個強有力的假設,而非絕對真理。

逐步執行計畫的意圖,但在編輯程式碼之前,必須針對實際儲存庫驗證每一項指令。前沿 AI 的計畫經常在以下方面失敗:不存在的檔案名稱、發明的匯入、不可用的函式庫、與儲存庫不符的模式、遺失的測試、理想化的架構以及破壞內部 API。

絕對不要批次處理大型變更。絕對不要跳過驗證。絕對不要隱藏不確定性。未經明確批准,絕對不要執行破壞性操作。

使用時機

  • 您收到由前沿 AI 撰寫的詳細、多步驟實作計畫
  • 該計畫包含 3 個以上不同的步驟,並帶有特定的檔案路徑和程式碼模式
  • 您正在使用一個可從執行紀律中受益的非前沿程式碼模型
  • 該計畫存在與實際程式碼庫衝突的風險

請勿用於:

  • 單一檔案變更或瑣碎的修復
  • 僅包含 1-2 個簡單步驟的計畫
  • 您在相同會話中自行撰寫的計畫
  • 使用者希望速度優先於安全性的快速迭代

核心工作流程

0. 前置檢查:建立儲存庫基準線

在觸碰任何檔案之前,了解儲存庫狀態並偵測既存失敗。

1. git status --short          # 儲存庫是否乾淨?
2. 檢查 package.json         # 可用的腳本、依賴項
3. 檢查 AGENTS.md, README.md # 專案慣例、指令
4. 從 package.json 腳本中偵測可用的驗證指令
5. 如果可用,執行成本最低的基準線驗證(lint 或 typecheck)

如果基準線已經失敗:

  • 明確記錄失敗:確切指令、退出狀態和簡短的錯誤摘要
  • 不要嘗試廣泛清理或修復不相關的問題
  • 僅當計畫中的變更可以與既存失敗隔離時才繼續
  • 不要將既存失敗歸因於您的實作

危險狀態偵測:

  • 如果 git status 顯示與計畫無關的未提交變更,請警告使用者
  • 如果 lockfiles 被修改,請警告使用者
  • 如果儲存庫處於衝突/正在變基的狀態,請停止並詢問

檢查點建議:

  • 如果儲存庫在開始前是乾淨的,建議在實作前建立一個檢查點提交
  • 除非使用者明確要求,否則不要建立提交

自動提交和自動推送

預設啟用自動提交和自動推送,除非使用者明確停用。

代理程式應提交每個經過驗證的邏輯工作單元,並將其推送到活躍的遠端工作分支,以便使用者稍後可以檢視歷史記錄。

在實作之前:

  • 識別當前分支;
  • 如果在 main、master、production、release 或其他受保護/主線分支上,則根據計畫推斷建立一個新的工作分支;
  • 如果已經在工作分支上,則繼續使用該分支;
  • 絕不直接推送到受保護/主線分支。

如果存在既存的未提交變更:

  • 不要自動將它們包含在代理程式的提交中;
  • 僅暫存與當前邏輯單元相關的檔案;
  • 如果無法安全地分離使用者變更和代理程式變更,請停止並報告衝突。

僅在以下情況全部滿足後才提交:

  • 邏輯單元已完成;
  • 驗證通過;
  • 差異已被檢查;
  • 提交具有一個連貫的目的。

使用 Conventional Commits:

type(scope): concise imperative summary

範例:

feat(auth): add session validation helper
fix(api): handle empty webhook payload
refactor(billing): extract invoice mapper
test(auth): cover expired session flow

1. 解析:提取計畫並進行現實檢查

閱讀整個計畫。提取有序的步驟。對於每個步驟,執行現實檢查:

檢查項目問題
檔案引用的檔案是否存在於儲存庫中?
函式庫引用的函式庫是否存在於 package.json 中?
模式儲存庫中是否已經有等效的實用程式/元件?
指令計畫的驗證指令是否可用?
依賴項此步驟是否依賴於前一步驟?
風險低 / 中 / 高 — 打破現有行為的可能性有多大?

如果某個步驟引用了不存在的檔案、不存在的函式庫、過時的模式或不可用的指令:在實作之前調整該步驟,同時保留計畫的意圖。

2. 追蹤:建立進度追蹤器

如果可用,使用 todowrite(OpenCode 的任務列表工具)。

如果 todowrite 不可用(例如,在預設禁用它的子代理程式中):

  • 在您的回應中建立一個可見的 markdown 核取清單
  • 在每個步驟後手動更新它
  • 將其用作進度的唯一真相來源
  • 如果實際上未使用該工具,不要假裝已使用

每個項目必須包含:實作動作、驗證方法以及預期觸及的檔案。

3. 實作:一次一個步驟

將當前步驟標記為 in_progress。僅實作該步驟。

  • 在編輯之前讀取目標檔案
  • 遵循既有的程式碼庫慣例(導入、命名、模式、架構)
  • 使計畫適應現有基礎架構(例如,如果計畫說「建立一個 toast 元件」,但專案使用 Sonner,則包裝 Sonner 而不是從頭開始建置)
  • 做出最小的一致變更
  • 不要實作未來的步驟,但在做出設計決策時要考慮下游依賴項
  • 不要執行不相關的清理、重構或格式化
  • 除非獲得明確批准,否則不要安裝依賴項

4. 驗證:分層驗證

在每個步驟之後,執行最狹義、最有意義的驗證。 不要每次都「lint everything」。

變更類型最低驗證更強的驗證
新檔案/元件lint 或 typecheck受影響的 typecheck
型別/介面變更typecheck受影響的測試
邏輯/函式變更針對性單元測試完整測試套件
API/伺服器變更針對性整合測試建置 + 端點檢查
UI 變更typecheck + build視覺/手動冒煙測試
組態/建置變更build必要時 clean install/build
資料庫/綱要變更dry-run/check 指令需要使用者批准

如果某個步驟不存在自動化驗證:執行手動審查並精確說明您檢查了什麼。

如果驗證失敗:

首次失敗 — 修復並重新驗證:

  • 僅修復由當前步驟引起的錯誤
  • 不要修復既存或不相關的錯誤
  • 立即重新驗證

重複失敗 — 不要盲目地繼續修補。 請參閱下方的「重複失敗處理」。

關鍵: 絕不要透過削弱斷言、刪除測試、移除行為、變更公開 API、抑制錯誤或隱藏失敗來使驗證通過 — 除非計畫明確要求且使用者批准。讓警報停止並不等於解決問題。

5. 差異:檢查變更

在驗證通過後,檢查實際變更了什麼:

git diff --stat          # 哪些檔案變更了?
git diff                 # 當差異夠小時進行審查

確認:

  • 僅預期的檔案被變更
  • 沒有發生不相關的格式化
  • 沒有 lockfiles 被變更(除非明確預期)
  • 沒有意外編輯到產生的檔案
  • 沒有引入機密、本機路徑或除錯日誌
  • 沒有意外刪除程式碼

如果差異超出預期範圍,請在繼續之前停止並修正。

6. 確認:標記完成

僅在實作、驗證和差異檢查都乾淨時:

  • 將該步驟標記為 completed
  • 用一句話總結變更內容
  • 將下一步驟標記為 in_progress

7. 最終:完整驗證 + 報告

在所有步驟完成後:

  • 執行最強的合理檢查:lint + typecheck + build + tests(使用專案指令)
  • 報告:完成的步驟、變更的檔案、驗證結果、所做的調整、既存失敗(如果有的話)、任何需要使用者審查的事項

重複失敗處理

如果驗證因相同根本原因而重複失敗,不要繼續應用小的盲目修復。 目標是檢測您是否在每次嘗試中學到了新東西,還是只是在隨機亂試。

當一個步驟多次失敗時:

  1. 停止修補。 停止進行小的調整並重新執行。
  2. 仔細重新閱讀錯誤輸出。 完整的堆疊追蹤,而不僅僅是第一行。
  3. 檢查差異和周遭程式碼。 git diff,閱讀相關的型別、介面、函式。
  4. 重新評估原始假設。 當前的實作策略是否正確?
  5. 分類失敗原因:
    • 對程式碼庫的假設不正確?
    • 儲存庫不匹配(計畫與現實)?
    • 選擇了錯誤的抽象?
    • 介面或型別不相容?
    • 缺少依賴項?
    • 過時的產出物?
    • 與您的變更無關的既存問題?
    • 驗證指令本身配置錯誤?
  6. 形成一個真正的新假設。 僅在您有了一個新假設後才重試。
  7. 考慮縮小範圍。 能否將該步驟拆分成更小的部分來隔離失敗?

關鍵規則: 不要重複相同的修復策略,除非從以下方面發現了新資訊:

  • 日誌
  • 堆疊追蹤
  • 差異
  • 測試
  • 儲存庫檢查
  • 文件

如果在多次嘗試後仍未出現新策略,請停止並清楚地報告阻礙:

阻礙:
- 驗證指令:`npm run build`
- 失敗檔案:`src/app/page.tsx`
- 根本問題假設:React Server Component 導入了僅限用戶端的 hook
- 已嘗試的策略:
  1. 將導入移至用戶端元件
  2. 將 hook 隔離到單獨的檔案中
  3. 檢查儲存庫中的現有模式
- 停止原因:
  儲存庫中沒有一致的模式可以安全地解決邊界問題
- 可能的下一步行動:
  使用者審查或架構釐清

一份清晰的阻礙報告總是比重複「仍然失敗」同時胡亂猜測要好。

使計畫適應現有程式碼

前沿 AI 的計畫經常與實際程式碼庫衝突。當發生這種情況時:

  1. 識別衝突 — 「計畫說 import { X } from 'uninstalled-lib' 但它不在 package.json 中」
  2. 適應,不要忽略 — 使用現有基礎架構來符合計畫的意圖
  3. 解釋適應 — 用一句話說明您變更了什麼以及為什麼
  4. 保留計畫的介面 — 如果計畫導出 useToast(),您的適應仍然應該導出 useToast(),即使內部實作不同

關鍵規則:

  • 如果儲存庫中已經有等效的原始工具,不要建立新的抽象
  • 除非計畫明確要求且使用者批准,否則不要安裝新的依賴項
  • 未經正當理由,不要變更架構或模式

未經明確使用者批准禁止進行

這些指令需要使用者說「是」才能執行:

破壞性:

  • rm -rf
  • git reset --hard
  • git clean -fd
  • git push --force

安裝(變更 lockfiles):

  • npm install
  • pnpm install
  • yarn install
  • bun install
  • npm audit fix

資料庫 / 基礎架構:

  • prisma migrate
  • prisma db push
  • supabase db push
  • docker compose down -v

組態:

  • 變更 .env 檔案
  • 修改全域工具配置
  • 執行部署/取消發布指令

大規模變更:

  • 廣泛格式化(對整個儲存庫執行 prettier/eslint --fix)
  • 在未經審查的情況下對多個檔案進行尋找和取代

如果不確定某個指令是否安全,請在執行前詢問。

常見錯誤

錯誤現實
「前沿 AI 這麼說,所以它一定是對的」前沿計畫是假設。根據實際儲存庫進行驗證。
「我會在最後一次驗證所有東西」錯誤會疊加。以適當的粒度驗證每個步驟。
「我已經讀過計畫了,我可以一次全部實作」批次實作 = 批次錯誤 + 更難除錯。
「我順便修一下既存的 lint 錯誤」不相關的清理會掩蓋您的變更實際做了什麼。不要這樣做。
「這個步驟很簡單,我不用檢查 git diff」簡單的編輯也可能意外刪除程式碼或格式化非預期的檔案。
「我會安裝計畫中提到的缺少的函式庫」先問。該函式庫可能是故意缺席或未經批准的。
「npm run build 是唯一重要的驗證」Build 又慢又廣泛。對中間步驟使用 lint/typecheck。
「如果失敗了,我就調整一下然後重新執行直到通過」在沒有新資訊的情況下盲目修補就是亂試。重新閱讀錯誤。先形成一個新的假設。
「又是同一個錯誤,讓我嘗試一個不同的微小變更」相同錯誤 + 相同策略 = 相同結果。改變策略,而不是修補。

紅旗 — 停止並重新評估

  • 「我之後的下一個步驟也會驗證」 — 現在就驗證。
  • 「前沿計畫比儲存庫更懂」 — 儲存庫是唯一真相來源。
  • 「這個函式庫沒有安裝但計畫需要它」 — 詢問使用者。不要靜默安裝。
  • 「差異比預期大但可能沒問題」 — 在繼續之前檢查並解釋。
  • 「我會批次處理步驟 2 和 3,因為它們相關」 — 一個步驟 = 一個驗證 + 差異循環。
  • 「有既存的 lint 錯誤,讓我先修復它們」 — 這不是您的工作。記錄它們。保持專注。
  • 「讓我在編輯這個檔案時順便格式化它」 — 分開的變更 = 分開的步驟。不要混在一起。
  • 「還是失敗,讓我再試一個快速修復」 — 停止修補。重新閱讀錯誤。先形成一個新的假設。
  • 「同一個錯誤 3 次了,再做一次微調可能有用」 — 相同錯誤 + 相同策略 = 亂試。改變策略或報告阻礙。
  • 「我直接重寫整個東西看看能不能修好」 — 在沒有理解失敗原因的情況下丟掉工作學不到任何東西。先診斷。
  • 「使用者很急,我跳過差異檢查」 — 5 秒的 git diff --stat 可以防止數小時的除錯。

快速參考

階段動作工具
前置檢查git status, 偵測指令, 基準線檢查Bash
解析 + 現實檢查閱讀計畫, 對照儲存庫驗證每個步驟Read + Glob
追蹤建立 todowrite

…

[為翻譯而截斷]

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

Build content-focused websites with Astro — zero JS by default, islands architecture, multi-framework components, and Markdown/MDX support.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Next.js App Router principles. Server Components, data fetching, routing patterns.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

相關技能