diff --git a/README.es.md b/README.es.md index 0655d96..227b98a 100644 --- a/README.es.md +++ b/README.es.md @@ -29,7 +29,7 @@ codex-workflows evita que el alcance crezca sin control durante toda la ejecuci | Alcance | El flujo contrasta la petición con el resultado deseado, las exclusiones expresas, el código existente y el coste aproximado. Lo que no justifica su coste se descarta antes de convertirse en arquitectura. | | Controles entre fases | Los requisitos, el diseño y el plan se revisan antes de autorizar la siguiente fase. Los agentes nuevos leen las decisiones aprobadas y la evidencia que necesitan, en vez de reconstruir la intención a partir de una conversación larga. | | Ejecución | Una vez aprobado el alcance de implementación, Codex ejecuta el conjunto de tareas de forma autónoma. Cada tarea supera su verificación específica y las comprobaciones aplicables del repositorio antes del commit de implementación. | -| Finalización | Revisiones independientes de código y seguridad inspeccionan el cambio completo. Las correcciones obligatorias vuelven al mismo ciclo de implementación y calidad; las mejoras opcionales pueden descartarse si hay argumentos para hacerlo. | +| Finalización | Las revisiones independientes de código y seguridad comprueban que el cambio terminado se ajuste al alcance aprobado y no contenga fallos importantes. Las correcciones obligatorias vuelven al mismo ciclo de implementación y calidad. | Este flujo requiere más llamadas a agentes y más tokens que una ejecución directa. Úsalo cuando proteger el resultado acordado compense ese coste. @@ -71,6 +71,7 @@ El prefijo `$` invoca una skill de forma explícita. Escribe `$recipe-` para ver | Diseñar y construir un frontend web con React / TypeScript | `$recipe-front-design` → `$recipe-front-plan` → `$recipe-front-build` | | Entregar juntos un cambio de backend y otro de frontend React | `$recipe-fullstack-implement` | | Revisar una implementación frente a su diseño | `$recipe-review` o `$recipe-front-review` | +| Definir o actualizar reglas de revisión propias del repositorio | `$recipe-quality-profile` | | Investigar un problema sin tocar el código | `$recipe-diagnose` | | Hacer un experimento desechable o un script puntual | Usa Codex directamente | @@ -88,7 +89,7 @@ flowchart LR D --> E[Planificar el trabajo dependiente] E --> F[Aprobar el alcance de implementación] F --> H[Por tarea: implementar, verificar, comprobar calidad y hacer commit] - H --> K[Verificación independiente de código y seguridad] + H --> K[Revisión independiente de código y seguridad] K -->|Corrección| H K -->|Cambian los requisitos o el diseño principal| B K -->|Aprobado| L[Finalizado] @@ -123,7 +124,7 @@ Separar los contextos evita que exploración, diseño, implementación y revisi - **Verificación**: Ejecutar la prueba de contrato y comprobar la estructura de respuesta documentada ``` -El [Task File Contract](.agents/skills/llm-friendly-context/references/task-template.md) lleva a la implementación la fuente, el resultado esperado, los archivos afectados y una verificación ejecutable. Solo añade un `Verification Focus` cuando una prueba podría pasar sin demostrar un comportamiento importante. Tras ejecutar la tarea, se aplican al cambio completo todos los controles pertinentes del repositorio antes del commit. Los revisores finales comparan el código terminado con los documentos aprobados y repiten la revisión después de las correcciones aceptadas. +El [Task File Contract](.agents/skills/llm-friendly-context/references/task-template.md) lleva a la implementación la fuente, el resultado esperado, los archivos afectados y una verificación ejecutable. Solo añade un `Verification Focus` cuando una prueba podría pasar sin demostrar un comportamiento importante. Tras ejecutar la tarea, se aplican al cambio completo todos los controles pertinentes del repositorio antes del commit. Los revisores finales comparan el código terminado con los documentos aprobados. También buscan cambios fuera del alcance aprobado y problemas importantes de calidad del código. Cuando se acepta una corrección, la siguiente revisión se centra en los controles que esa corrección podría afectar. Ejecuta `$recipe-quality-profile` para definir reglas de revisión adicionales en `docs/project-context/quality.yaml` a partir de la evidencia del propio repositorio. --- @@ -199,7 +200,8 @@ Invoca un flujo con `$recipe-name` en Codex. Escribe `$recipe-` y usa el autocom | `$recipe-plan` | Design Doc → esqueletos selectivos de integración/E2E → Work Plan | Planificación desde un Design Doc aprobado | | `$recipe-prepare-implementation` | Prepara las herramientas locales ya existentes que necesita un Work Plan aprobado | Petición expresa de preparación o capacidad necesaria no disponible | | `$recipe-build` | Ejecuta tareas de backend con validación entre pasos | Retomar una implementación de backend | -| `$recipe-review` | Verifica el Design Doc y la seguridad, con correcciones aprobadas opcionales | Revisión tras implementar | +| `$recipe-review` | Revisa el alcance de implementación, el cumplimiento del Design Doc, la calidad del código y la seguridad; aplica las correcciones aprobadas por el usuario | Revisión tras implementar | +| `$recipe-quality-profile` | Define o actualiza reglas de revisión propias del repositorio en `docs/project-context/quality.yaml` | Configuración y mantenimiento de las reglas de revisión | | `$recipe-diagnose` | Investigación → verificación del punto de fallo → solución | Investigación de errores | | `$recipe-reverse-engineer` | Genera PRD y Design Docs a partir del código existente | Documentar sistemas heredados | | `$recipe-add-integration-tests` | Añade pruebas de integración/E2E a partir del Design Doc | Mejorar la cobertura del código existente | @@ -213,7 +215,7 @@ Invoca un flujo con `$recipe-name` en Codex. Escribe `$recipe-` y usa el autocom | `$recipe-front-adjust` | Ajuste acotado de UI con pruebas del repositorio, material aportado o fuentes externas necesarias | Cambios puntuales de UI después de implementar | | `$recipe-front-plan` | Design Doc frontend → esqueletos selectivos de integración/E2E → Work Plan | Planificación frontend | | `$recipe-front-build` | Ejecuta tareas frontend con verificación específica y controles de calidad | Retomar una implementación frontend | -| `$recipe-front-review` | Verifica cumplimiento y seguridad frontend, con correcciones React aprobadas opcionales | Revisión frontend posterior a la implementación | +| `$recipe-front-review` | Revisa el alcance, el cumplimiento, la calidad del código y la seguridad del frontend; aplica las correcciones React aprobadas por el usuario | Revisión frontend posterior a la implementación | ### Fullstack (entre capas) @@ -302,7 +304,7 @@ Codex crea estos agentes cuando un flujo los necesita. No hace falta aprender su | Agente | Función | |--------|---------| -| `code-reviewer` | Valida el cumplimiento del Design Doc | +| `code-reviewer` | Contrasta la implementación terminada con el alcance y los documentos aprobados, y señala problemas importantes de calidad del código | | `code-verifier` | Comprueba la coherencia entre documentos y código | | `security-reviewer` | Revisa la seguridad después de implementar | | `rule-advisor` | Elige skills para tareas independientes no cubiertas por un flujo | diff --git a/README.ja.md b/README.ja.md index 463ecfb..6e08208 100644 --- a/README.ja.md +++ b/README.ja.md @@ -29,7 +29,7 @@ codex-workflowsは、実行中を通してこうした拡大を抑えます。 | スコープ | 依頼内容を、目指す成果、明示的な除外事項、既存コード、実装の概算コストと照合します。コストに見合わない作業は、アーキテクチャになる前に取り除きます。 | | フェーズゲート | 要件・設計・計画の成果物を確認し、合格したものだけが次のフェーズを開始できます。新しいエージェントは、長い会話から意図を組み立て直すのではなく、承認済みの判断と必要な根拠を読みます。 | | 実行 | 実装が承認されると、Codexがタスク一式を自律的に実行します。各タスクは実装コミットの前に、対象を絞った検証と該当するリポジトリチェックを通過します。 | -| 完了 | 独立したコード検証とセキュリティ検証が、変更全体を確認します。必須の修正は同じ実装・品質サイクルに戻り、任意の堅牢化は根拠を示したうえで見送れます。 | +| 完了 | 独立したコードレビューとセキュリティレビューで、完成した変更が承認済みの範囲に収まり、重大な問題がないことを確認します。必須の修正は同じ実装・品質サイクルに戻します。 | このワークフローは、Codexを直接使う場合よりエージェント呼び出しとトークンを多く消費します。合意した成果を守る価値が、そのコストを上回るときに使ってください。 @@ -71,6 +71,7 @@ $recipe-implement JWTによるユーザー認証を追加する | React / TypeScriptのWebフロントエンドを設計・実装する | `$recipe-front-design` → `$recipe-front-plan` → `$recipe-front-build` | | バックエンドとReactフロントエンドをまとめて変更する | `$recipe-fullstack-implement` | | 設計どおりに実装されているかレビューする | `$recipe-review` または `$recipe-front-review` | +| リポジトリ固有のレビュールールを定義・更新する | `$recipe-quality-profile` | | コードを変えずに問題を調査する | `$recipe-diagnose` | | 使い捨ての検証や単発スクリプトを実行する | Codexを直接使う | @@ -88,7 +89,7 @@ flowchart LR D --> E[依存関係を踏まえて作業を計画] E --> F[実装範囲を承認] F --> H[タスクごとに実装・検証・品質確認・コミット] - H --> K[独立したコード検証とセキュリティ検証] + H --> K[独立したコードレビューとセキュリティレビュー] K -->|修正あり| H K -->|要件または主要設計が変更| B K -->|合格| L[完了] @@ -123,7 +124,7 @@ ADRを作るのは、現在のスコープに属し、長く残る選択で、 - **検証**: 契約テストを実行し、文書どおりのレスポンス形式を確認 ``` -[Task File Contract](.agents/skills/llm-friendly-context/references/task-template.md)は、根拠、期待する結果、対象ファイル、実行可能な検証方法を実装フェーズへ渡します。テストが通っても重要な挙動を証明できないおそれがある場合だけ、`Verification Focus`を追加します。実行後は、コミット前にタスクの変更全体へ該当するリポジトリチェックをかけます。最終レビュアーは、承認済み文書と完成したコードを照合し、採用された修正後にもう一度確認します。 +[Task File Contract](.agents/skills/llm-friendly-context/references/task-template.md)は、根拠、期待する結果、対象ファイル、実行可能な検証方法を実装フェーズへ渡します。テストが通っても重要な挙動を証明できないおそれがある場合だけ、`Verification Focus`を追加します。実行後は、コミット前にタスクの変更全体へ該当するリポジトリチェックをかけます。最終レビュアーは、完成したコードを承認済み文書と照合します。さらに、承認範囲を超えた実装や重大なコード品質上の問題がないかも確認します。修正を採用したあとの再レビューでは、その修正の影響を受ける項目に対象を絞ります。`$recipe-quality-profile`を実行すると、リポジトリ内の根拠をもとに、固有のレビュールールを`docs/project-context/quality.yaml`へ追加できます。 --- @@ -199,7 +200,8 @@ Codexでは`$recipe-name`でレシピを呼び出します。`$recipe-`まで入 | `$recipe-plan` | Design Doc → 必要な統合/E2Eテストのひな型 → Work Plan | 承認済みDesign Docからの計画 | | `$recipe-prepare-implementation` | 承認済みWork Planに必要な既存のリポジトリ内ツールを準備 | 明示的なセットアップ依頼、または必要なタスク機能が利用できない場合 | | `$recipe-build` | ステップ間の検証を含むバックエンドタスクの実行 | バックエンド実装の再開 | -| `$recipe-review` | Design Doc準拠とセキュリティの検証、必要に応じて承認済み修正 | 実装後の確認 | +| `$recipe-review` | 実装範囲、Design Doc準拠、コード品質、セキュリティをレビューし、ユーザーが承認した修正を適用 | 実装後の確認 | +| `$recipe-quality-profile` | リポジトリ固有のレビュールールを`docs/project-context/quality.yaml`に定義・更新 | レビューポリシーの設定・保守 | | `$recipe-diagnose` | 問題調査 → 障害点の検証 → 解決策 | 不具合調査 | | `$recipe-reverse-engineer` | 既存コードからPRDとDesign Docを生成 | レガシーシステムの文書化 | | `$recipe-add-integration-tests` | Design Docをもとに統合/E2Eテストを追加 | 既存コードのテスト拡充 | @@ -213,7 +215,7 @@ Codexでは`$recipe-name`でレシピを呼び出します。`$recipe-`まで入 | `$recipe-front-adjust` | リポジトリ、提供資料、必要な外部根拠に基づく、範囲を絞ったUI調整 | 実装後の部分的なUI変更 | | `$recipe-front-plan` | フロントエンドDesign Doc → 必要な統合/E2Eテストのひな型 → Work Plan | フロントエンドの計画フェーズ | | `$recipe-front-build` | 対象を絞った検証と品質チェックを含むフロントエンドタスクの実行 | フロントエンド実装の再開 | -| `$recipe-front-review` | フロントエンド準拠・セキュリティ検証と、必要に応じた承認済みReact修正 | フロントエンド実装後の確認 | +| `$recipe-front-review` | フロントエンドの範囲、準拠状況、コード品質、セキュリティをレビューし、ユーザーが承認したReact修正を適用 | フロントエンド実装後の確認 | ### フルスタック(レイヤー横断) @@ -302,7 +304,7 @@ Webフロントエンドで使うTypeScript向けには、Reactアプリケー | エージェント | 役割 | |--------------|------| -| `code-reviewer` | Design Docへの準拠を検証 | +| `code-reviewer` | 完成した実装を承認範囲や準拠すべき文書と照合し、重大なコード品質上の問題を確認 | | `code-verifier` | 文書とコードの整合性を検証 | | `security-reviewer` | 実装後のセキュリティ準拠をレビュー | | `rule-advisor` | レシピの管理外にある単独タスクのスキルを選定 | diff --git a/README.ko.md b/README.ko.md index 27f7171..cf26463 100644 --- a/README.ko.md +++ b/README.ko.md @@ -29,7 +29,7 @@ codex-workflows는 실행 내내 이런 범위 확장을 제어합니다. | 범위 | 요청을 원하는 결과, 명시적 제외 사항, 기존 코드, 대략적인 구현 비용과 비교합니다. 비용만큼 가치가 없는 작업은 아키텍처가 되기 전에 제거합니다. | | 단계 게이트 | 요구사항, 설계, 계획 결과물을 확인한 뒤에만 다음 단계를 허용합니다. 새 에이전트는 긴 대화에서 의도를 다시 추측하는 대신 승인된 결정과 필요한 근거를 읽습니다. | | 실행 | 구현이 승인되면 Codex가 작업 묶음을 자율적으로 수행합니다. 각 작업은 구현 커밋 전에 해당 작업에 맞춘 검증과 저장소에서 요구하는 검사를 통과합니다. | -| 완료 | 독립적인 코드 및 보안 검증이 변경 전체를 살핍니다. 반드시 고쳐야 할 문제는 같은 구현·품질 주기로 돌아가며, 선택적인 보강은 근거를 제시하고 하지 않을 수 있습니다. | +| 완료 | 독립적인 코드 리뷰와 보안 리뷰를 통해 완성된 변경이 승인 범위를 벗어나지 않았고 중대한 문제가 없는지 확인합니다. 반드시 필요한 수정은 같은 구현·품질 주기로 돌려보냅니다. | 이 워크플로는 Codex를 직접 실행할 때보다 더 많은 에이전트 호출과 토큰을 사용합니다. 승인된 결과를 지키는 일이 그 비용보다 중요할 때 사용하세요. @@ -71,6 +71,7 @@ $recipe-implement JWT 사용자 인증 추가 | React / TypeScript 웹 프런트엔드를 설계하고 구현 | `$recipe-front-design` → `$recipe-front-plan` → `$recipe-front-build` | | 백엔드와 React 프런트엔드 변경을 함께 구현 | `$recipe-fullstack-implement` | | 설계에 맞게 구현되었는지 리뷰 | `$recipe-review` 또는 `$recipe-front-review` | +| 저장소별 리뷰 규칙 정의 또는 업데이트 | `$recipe-quality-profile` | | 코드를 바꾸지 않고 문제 조사 | `$recipe-diagnose` | | 일회성 실험이나 단발성 스크립트 실행 | Codex 직접 사용 | @@ -88,7 +89,7 @@ flowchart LR D --> E[의존 작업 계획] E --> F[구현 범위 승인] F --> H[작업별 구현, 검증, 품질 검사 및 커밋] - H --> K[독립 코드 및 보안 검증] + H --> K[독립 코드 및 보안 리뷰] K -->|수정 필요| H K -->|요구사항 또는 주요 설계 변경| B K -->|통과| L[완료] @@ -123,7 +124,7 @@ ADR은 현재 범위에 속하고 오래 유지되는 선택에 실질적으로 - **검증**: 계약 테스트를 실행하고 문서에 정의된 응답 형태 확인 ``` -[Task File Contract](.agents/skills/llm-friendly-context/references/task-template.md)는 출처, 의도한 결과, 대상 파일, 실행 가능한 검증을 구현 단계로 전달합니다. 테스트가 통과해도 중요한 동작을 증명하지 못할 수 있을 때만 `Verification Focus`를 추가합니다. 실행 후에는 커밋 전에 작업 변경 전체에 해당 저장소 검사를 적용합니다. 최종 리뷰어는 승인 문서와 완성된 코드를 비교하고, 채택된 수정이 끝나면 다시 검토합니다. +[Task File Contract](.agents/skills/llm-friendly-context/references/task-template.md)는 출처, 의도한 결과, 대상 파일, 실행 가능한 검증을 구현 단계로 전달합니다. 테스트가 통과해도 중요한 동작을 증명하지 못할 수 있을 때만 `Verification Focus`를 추가합니다. 실행 후에는 커밋 전에 작업 변경 전체에 해당 저장소 검사를 적용합니다. 최종 리뷰어는 완성된 코드를 승인 문서와 대조합니다. 또한 승인 범위를 벗어난 구현이나 중대한 코드 품질 문제가 있는지 확인합니다. 수정이 채택되면 다음 리뷰에서는 해당 수정의 영향을 받을 수 있는 검사 항목에 집중합니다. `$recipe-quality-profile`을 실행하면 저장소의 근거를 바탕으로 `docs/project-context/quality.yaml`에 리뷰 규칙을 추가할 수 있습니다. --- @@ -199,7 +200,8 @@ Codex에서 `$recipe-name`으로 레시피를 호출합니다. `$recipe-`를 입 | `$recipe-plan` | Design Doc → 필요한 통합/E2E 골격 → Work Plan | 승인된 Design Doc에서 계획 수립 | | `$recipe-prepare-implementation` | 승인된 Work Plan에 필요한 기존 저장소 내부 도구 준비 | 명시적인 설정 요청 또는 필요한 작업 기능이 없을 때 | | `$recipe-build` | 단계 사이 검증과 함께 백엔드 작업 실행 | 백엔드 구현 재개 | -| `$recipe-review` | Design Doc 준수 및 보안 검증, 필요시 승인된 수정 | 구현 후 확인 | +| `$recipe-review` | 구현 범위, Design Doc 준수 여부, 코드 품질 및 보안을 리뷰하고 사용자가 승인한 수정 적용 | 구현 후 확인 | +| `$recipe-quality-profile` | `docs/project-context/quality.yaml`에 저장소별 리뷰 규칙 정의 또는 업데이트 | 리뷰 정책 설정 및 유지보수 | | `$recipe-diagnose` | 문제 조사 → 장애 지점 검증 → 해결책 | 버그 조사 | | `$recipe-reverse-engineer` | 기존 코드에서 PRD와 Design Doc 생성 | 레거시 시스템 문서화 | | `$recipe-add-integration-tests` | Design Doc에서 통합/E2E 테스트 추가 | 기존 코드의 테스트 범위 확대 | @@ -213,7 +215,7 @@ Codex에서 `$recipe-name`으로 레시피를 호출합니다. `$recipe-`를 입 | `$recipe-front-adjust` | 저장소, 제공 자료 또는 필요한 외부 근거를 사용한 집중 UI 조정 | 구현 후의 좁은 UI 변경 | | `$recipe-front-plan` | 프런트엔드 Design Doc → 필요한 통합/E2E 골격 → Work Plan | 프런트엔드 계획 단계 | | `$recipe-front-build` | 작업에 맞춘 검증과 품질 검사를 포함한 프런트엔드 작업 실행 | 프런트엔드 구현 재개 | -| `$recipe-front-review` | 프런트엔드 준수 및 보안 검증, 필요시 승인된 React 수정 | 프런트엔드 구현 후 확인 | +| `$recipe-front-review` | 프런트엔드 범위, 준수 여부, 코드 품질 및 보안을 리뷰하고 사용자가 승인한 React 수정 적용 | 프런트엔드 구현 후 확인 | ### 풀스택(계층 간) @@ -302,7 +304,7 @@ React 애플리케이션을 포함한 웹 프런트엔드 TypeScript용 참고 | 에이전트 | 역할 | |----------|------| -| `code-reviewer` | Design Doc 준수 검증 | +| `code-reviewer` | 완성된 구현을 승인 범위 및 기준 문서와 대조하고 중대한 코드 품질 문제를 확인 | | `code-verifier` | 문서와 코드 일치 검증 | | `security-reviewer` | 구현 후 보안 준수 리뷰 | | `rule-advisor` | 레시피 밖의 단독 작업을 위한 스킬 선택 | diff --git a/README.md b/README.md index b30cb86..28ad464 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ codex-workflows controls that expansion throughout the run: | Scope | The workflow compares the request with the desired outcome, explicit exclusions, the existing code, and rough implementation cost. Work that does not earn its cost is removed before it becomes architecture. | | Phase gates | Requirements, design, and planning outputs are checked before they can authorize the next phase. Fresh agents read the approved decisions and evidence they need instead of reconstructing intent from a long conversation. | | Execution | After implementation approval, Codex executes the task set autonomously. Each task passes its focused verification and applicable repository checks before its implementation commit. | -| Completion | Independent code and security review inspects the completed change for approved scope and material failures. Required corrections return through the same implementation and quality cycle. | +| Completion | Independent code and security reviews check that the completed change stays within the approved scope and has no serious problems. Required corrections return through the same implementation and quality cycle. | This workflow uses more agent calls and tokens than direct execution. Use it when protecting the approved outcome is worth that cost. @@ -71,7 +71,7 @@ $recipe-implement Add user authentication with JWT | Design and build a React / TypeScript web frontend | `$recipe-front-design` → `$recipe-front-plan` → `$recipe-front-build` | | Deliver a backend and React frontend change together | `$recipe-fullstack-implement` | | Review an implementation against its design | `$recipe-review` or `$recipe-front-review` | -| Create or maintain repository-specific review policy | `$recipe-quality-profile` | +| Define or update repository-specific review rules | `$recipe-quality-profile` | | Investigate a problem without changing code | `$recipe-diagnose` | | Run a throwaway experiment or one-shot script | Use Codex directly | @@ -124,7 +124,7 @@ Fresh contexts keep exploration, design, implementation, and review from silentl - **Verification**: Run the contract test and observe the documented response shape ``` -The [Task File Contract](.agents/skills/llm-friendly-context/references/task-template.md) carries the source, intended result, target files, and executable verification into implementation. It adds a `Verification Focus` only when a test could pass without proving one important behavior. After execution, the applicable repository checks run against the complete task change before commit. Final reviewers compare the approved documents with the completed code, check for unsupported implementation scope and material code-quality failures, and rerun only the correction-affected review boundary after accepted corrections. `docs/project-context/quality.yaml`, generated or updated with `$recipe-quality-profile`, can add evidence-backed repository policy to that review. +The [Task File Contract](.agents/skills/llm-friendly-context/references/task-template.md) carries the source, intended result, target files, and executable verification into implementation. It adds a `Verification Focus` only when a test could pass without proving one important behavior. After execution, the applicable repository checks run against the complete task change before commit. Final reviewers compare the completed code with the approved documents. They also look for work outside the approved scope and serious code-quality problems. When a correction is accepted, the next review focuses on the checks that correction could affect. Run `$recipe-quality-profile` to define additional review rules in `docs/project-context/quality.yaml` based on evidence from the repository. --- @@ -201,8 +201,8 @@ Invoke recipes with `$recipe-name` in Codex. Type `$recipe-` and use tab complet | `$recipe-plan` | Design Doc → selective integration/E2E skeletons → work plan | Planning phase from an approved Design Doc | | `$recipe-prepare-implementation` | Prepare existing repository-local tools needed by an approved Work Plan | Explicit setup request or a concrete task capability is unavailable | | `$recipe-build` | Execute backend tasks with validation between steps | Resume backend implementation | -| `$recipe-review` | Implementation scope, Design Doc compliance, code quality, and security review with user-approved corrections | Post-implementation check | -| `$recipe-quality-profile` | Generate or update `docs/project-context/quality.yaml` from repository evidence | Repository review-policy setup and maintenance | +| `$recipe-review` | Review implementation scope, Design Doc compliance, code quality, and security; apply corrections approved by the user | Post-implementation check | +| `$recipe-quality-profile` | Define or update repository-specific review rules in `docs/project-context/quality.yaml` | Set up or maintain review rules | | `$recipe-diagnose` | Problem investigation → failure-point verification → solution | Bug investigation | | `$recipe-reverse-engineer` | Generate PRD + Design Docs from existing code | Legacy system documentation | | `$recipe-add-integration-tests` | Add integration/E2E tests from Design Doc | Test coverage for existing code | @@ -216,7 +216,7 @@ Invoke recipes with `$recipe-name` in Codex. Type `$recipe-` and use tab complet | `$recipe-front-adjust` | Focused UI adjustment using repository, supplied, or required external evidence | Focused UI changes after implementation | | `$recipe-front-plan` | Frontend Design Doc → selective integration/E2E skeletons → work plan | Frontend planning phase | | `$recipe-front-build` | Execute frontend tasks with focused verification and quality checks | Resume frontend implementation | -| `$recipe-front-review` | Frontend scope, compliance, code quality, and security review with user-approved React corrections | Frontend post-implementation check | +| `$recipe-front-review` | Review frontend scope, compliance, code quality, and security; apply React corrections approved by the user | Frontend post-implementation check | ### Fullstack (Cross-Layer) @@ -305,7 +305,7 @@ Codex spawns these as needed during recipe execution. You do not need to learn t | Agent | Role | |-------|------| -| `code-reviewer` | Completed implementation scope, governing-source compliance, and material code-quality review | +| `code-reviewer` | Checks the completed implementation against the approved scope and documents, and flags serious code-quality problems | | `code-verifier` | Document-code consistency verification | | `security-reviewer` | Security compliance review after implementation | | `rule-advisor` | Skill selection for standalone work not already governed by a recipe | diff --git a/README.pt-BR.md b/README.pt-BR.md index 22f1319..c6b91d4 100644 --- a/README.pt-BR.md +++ b/README.pt-BR.md @@ -29,7 +29,7 @@ O codex-workflows controla esse crescimento de escopo ao longo de toda a execuç | Escopo | O fluxo compara o pedido com o resultado desejado, as exclusões explícitas, o código existente e o custo aproximado de implementação. O trabalho que não justifica seu custo é removido antes de virar arquitetura. | | Controles entre fases | Os resultados de requisitos, design e planejamento são revisados antes de autorizar a próxima fase. Novos agentes leem as decisões aprovadas e as evidências necessárias, em vez de reconstruir a intenção a partir de uma conversa longa. | | Execução | Depois que o escopo de implementação é aprovado, o Codex executa o conjunto de tarefas de forma autônoma. Cada tarefa passa por sua verificação específica e pelas checagens aplicáveis do repositório antes do commit de implementação. | -| Conclusão | Revisões independentes de código e segurança examinam toda a mudança. Correções obrigatórias voltam ao mesmo ciclo de implementação e qualidade; reforços opcionais podem ser recusados quando houver justificativa. | +| Conclusão | Revisões independentes de código e segurança confirmam que a mudança concluída permanece dentro do escopo aprovado e não contém falhas graves. As correções obrigatórias voltam ao mesmo ciclo de implementação e qualidade. | Esse fluxo usa mais chamadas de agentes e mais tokens do que uma execução direta. Use-o quando proteger o resultado aprovado valer esse custo. @@ -71,6 +71,7 @@ O prefixo `$` invoca uma skill explicitamente. Digite `$recipe-` para ver os flu | Projetar e construir um frontend web com React / TypeScript | `$recipe-front-design` → `$recipe-front-plan` → `$recipe-front-build` | | Entregar juntos uma mudança de backend e outra de frontend React | `$recipe-fullstack-implement` | | Revisar uma implementação com base no design | `$recipe-review` ou `$recipe-front-review` | +| Definir ou atualizar regras de revisão específicas do repositório | `$recipe-quality-profile` | | Investigar um problema sem alterar o código | `$recipe-diagnose` | | Fazer um experimento descartável ou um script pontual | Use o Codex diretamente | @@ -88,7 +89,7 @@ flowchart LR D --> E[Planejar trabalhos dependentes] E --> F[Aprovar o escopo da implementação] F --> H[Por tarefa: implementar, verificar, checar qualidade e fazer commit] - H --> K[Verificação independente de código e segurança] + H --> K[Revisão independente de código e segurança] K -->|Correção| H K -->|Requisito ou design principal mudou| B K -->|Aprovado| L[Concluído] @@ -123,7 +124,7 @@ Separar os contextos evita que exploração, design, implementação e revisão - **Verificação**: Executar o teste de contrato e observar o formato de resposta documentado ``` -O [Task File Contract](.agents/skills/llm-friendly-context/references/task-template.md) leva para a implementação a fonte, o resultado esperado, os arquivos-alvo e uma verificação executável. Ele só acrescenta um `Verification Focus` quando um teste pode passar sem comprovar um comportamento importante. Após a execução, todas as checagens aplicáveis do repositório rodam sobre a mudança completa antes do commit. Os revisores finais comparam o código concluído com os documentos aprovados e repetem a análise depois das correções aceitas. +O [Task File Contract](.agents/skills/llm-friendly-context/references/task-template.md) leva para a implementação a fonte, o resultado esperado, os arquivos-alvo e uma verificação executável. Ele só acrescenta um `Verification Focus` quando um teste pode passar sem comprovar um comportamento importante. Após a execução, todas as checagens aplicáveis do repositório rodam sobre a mudança completa antes do commit. Os revisores finais comparam o código concluído com os documentos aprovados. Eles também procuram mudanças fora do escopo aprovado e problemas sérios de qualidade do código. Quando uma correção é aceita, a revisão seguinte se concentra nas verificações que ela pode afetar. Execute `$recipe-quality-profile` para definir outras regras de revisão em `docs/project-context/quality.yaml` com base nas evidências do próprio repositório. --- @@ -199,7 +200,8 @@ No Codex, use `$recipe-name` para invocar um fluxo. Digite `$recipe-` e use o pr | `$recipe-plan` | Design Doc → estruturas seletivas de testes de integração/E2E → Work Plan | Planejamento a partir de um Design Doc aprovado | | `$recipe-prepare-implementation` | Prepara as ferramentas locais já existentes exigidas por um Work Plan aprovado | Pedido explícito de preparação ou recurso necessário indisponível | | `$recipe-build` | Executa tarefas de backend com validação entre etapas | Retomar uma implementação de backend | -| `$recipe-review` | Valida conformidade com o Design Doc e segurança, com correções aprovadas opcionais | Revisão após a implementação | +| `$recipe-review` | Revisa o escopo de implementação, a conformidade com o Design Doc, a qualidade do código e a segurança; aplica as correções aprovadas pelo usuário | Revisão após a implementação | +| `$recipe-quality-profile` | Define ou atualiza regras de revisão específicas do repositório em `docs/project-context/quality.yaml` | Configuração e manutenção das regras de revisão | | `$recipe-diagnose` | Investigação → verificação do ponto de falha → solução | Investigação de bugs | | `$recipe-reverse-engineer` | Gera PRD e Design Docs com base no código existente | Documentação de sistemas legados | | `$recipe-add-integration-tests` | Adiciona testes de integração/E2E a partir do Design Doc | Ampliar a cobertura do código existente | @@ -213,7 +215,7 @@ No Codex, use `$recipe-name` para invocar um fluxo. Digite `$recipe-` e use o pr | `$recipe-front-adjust` | Ajuste delimitado de UI com evidências do repositório, material fornecido ou fontes externas necessárias | Mudanças pontuais de UI após a implementação | | `$recipe-front-plan` | Design Doc frontend → estruturas seletivas de integração/E2E → Work Plan | Fase de planejamento frontend | | `$recipe-front-build` | Executa tarefas frontend com verificação específica e checagens de qualidade | Retomar uma implementação frontend | -| `$recipe-front-review` | Valida conformidade e segurança frontend, com correções React aprovadas opcionais | Revisão frontend após a implementação | +| `$recipe-front-review` | Revisa o escopo, a conformidade, a qualidade do código e a segurança do frontend; aplica as correções React aprovadas pelo usuário | Revisão frontend após a implementação | ### Fullstack (entre camadas) @@ -302,7 +304,7 @@ O Codex cria esses agentes conforme a necessidade durante a execução dos fluxo | Agente | Função | |--------|--------| -| `code-reviewer` | Valida a conformidade com o Design Doc | +| `code-reviewer` | Compara a implementação concluída com o escopo e os documentos aprovados, e aponta problemas sérios de qualidade do código | | `code-verifier` | Verifica a consistência entre documentos e código | | `security-reviewer` | Revisa a segurança depois da implementação | | `rule-advisor` | Seleciona skills para tarefas avulsas fora dos fluxos existentes | diff --git a/README.zh-CN.md b/README.zh-CN.md index c00a575..22da9c8 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -29,7 +29,7 @@ codex-workflows会在整个执行过程中约束这种范围膨胀: | 范围 | 工作流会对照预期结果、明确排除项、现有代码和大致实现成本来检查需求。投入与收益不相称的工作,会在演变成架构设计之前被删掉。 | | 阶段门槛 | 需求、设计和计划的产出必须先通过检查,才能授权下一阶段。新代理直接读取已经批准的决策和所需依据,无须从一段很长的对话中重新猜测意图。 | | 执行 | 实现范围获批后,Codex会自主完成整组任务。每项任务都要通过针对性验证和仓库要求的检查,之后才会提交实现。 | -| 完成 | 独立的代码和安全评审会检查全部改动。必须修复的问题会回到相同的实现与质量流程;可选的加固项则可以在有依据的情况下不做。 | +| 完成 | 独立的代码评审和安全评审会确认最终改动未超出已批准范围,且不存在重大问题。必须修复的问题会回到同一套实现与质量流程。 | 与直接执行相比,这套工作流会调用更多代理、消耗更多token。只有当保护既定目标值得这笔成本时,才需要使用它。 @@ -71,6 +71,7 @@ $recipe-implement 使用JWT添加用户认证 | 设计并实现React / TypeScript Web前端 | `$recipe-front-design` → `$recipe-front-plan` → `$recipe-front-build` | | 同时交付后端和React前端改动 | `$recipe-fullstack-implement` | | 按照设计评审实现 | `$recipe-review` 或 `$recipe-front-review` | +| 定义或更新仓库专属评审规则 | `$recipe-quality-profile` | | 调查问题但不修改代码 | `$recipe-diagnose` | | 做一次性实验或临时脚本 | 直接使用Codex | @@ -88,7 +89,7 @@ flowchart LR D --> E[规划存在依赖关系的工作] E --> F[批准实现范围] F --> H[逐项实现、验证、质量检查并提交] - H --> K[独立代码和安全验证] + H --> K[独立代码评审和安全评审] K -->|需要修正| H K -->|需求或主要设计发生变化| B K -->|通过| L[完成] @@ -123,7 +124,7 @@ flowchart LR - **验证**: 运行契约测试,确认响应结构符合文档 ``` -[Task File Contract](.agents/skills/llm-friendly-context/references/task-template.md)会把来源、预期结果、目标文件和可执行的验证方法传递到实现阶段。只有在测试可能通过、却没有证明某项关键行为时,才会增加`Verification Focus`。任务执行完毕后,完整改动必须在提交前通过适用的仓库检查。最终评审者会将完成的代码与已批准文档逐项对照,并在接受的修正完成后重新检查。 +[Task File Contract](.agents/skills/llm-friendly-context/references/task-template.md)会把来源、预期结果、目标文件和可执行的验证方法传递到实现阶段。只有在测试可能通过、却没有证明某项关键行为时,才会增加`Verification Focus`。任务执行完毕后,完整改动必须在提交前通过适用的仓库检查。最终评审者会将完成的代码与已批准文档逐项对照,同时检查是否存在超出批准范围的实现或重大的代码质量问题。接受修正后,下一轮评审只聚焦于可能受该修正影响的检查项。运行`$recipe-quality-profile`,可根据仓库中的依据,在`docs/project-context/quality.yaml`中定义额外的专属评审规则。 --- @@ -199,7 +200,8 @@ npx codex-workflows status --user | `$recipe-plan` | Design Doc → 按需生成集成/E2E测试骨架 → Work Plan | 根据已批准的Design Doc制定计划 | | `$recipe-prepare-implementation` | 准备已批准Work Plan所需的现有仓库内工具 | 明确要求准备环境,或任务所需能力不可用 | | `$recipe-build` | 执行后端任务,并在各步骤之间验证 | 继续后端实现 | -| `$recipe-review` | 检查Design Doc符合性和安全性,并按需完成已批准修正 | 实现后检查 | +| `$recipe-review` | 评审实现范围、Design Doc符合性、代码质量和安全性,并应用用户批准的修正 | 实现后检查 | +| `$recipe-quality-profile` | 在`docs/project-context/quality.yaml`中定义或更新仓库专属评审规则 | 设置和维护评审策略 | | `$recipe-diagnose` | 调查问题 → 验证故障点 → 提出解决方案 | 缺陷调查 | | `$recipe-reverse-engineer` | 从现有代码生成PRD和Design Doc | 遗留系统文档化 | | `$recipe-add-integration-tests` | 根据Design Doc添加集成/E2E测试 | 为现有代码补充测试 | @@ -213,7 +215,7 @@ npx codex-workflows status --user | `$recipe-front-adjust` | 根据仓库、已有资料或必要外部依据进行针对性UI调整 | 实现后的局部UI修改 | | `$recipe-front-plan` | 前端Design Doc → 按需生成集成/E2E测试骨架 → Work Plan | 前端规划阶段 | | `$recipe-front-build` | 执行前端任务,并进行针对性验证和质量检查 | 继续前端实现 | -| `$recipe-front-review` | 检查前端符合性和安全性,并按需完成已批准的React修正 | 前端实现后检查 | +| `$recipe-front-review` | 评审前端范围、符合性、代码质量和安全性,并应用用户批准的React修正 | 前端实现后检查 | ### 全栈(跨层) @@ -302,7 +304,7 @@ PRD、ADR、UI Spec和Design Doc属于需要长期保存的项目文档,应当 | 代理 | 职责 | |------|------| -| `code-reviewer` | 验证实现是否符合Design Doc | +| `code-reviewer` | 对照批准范围和约束文档检查最终实现,并指出重大的代码质量问题 | | `code-verifier` | 验证文档与代码的一致性 | | `security-reviewer` | 实现后进行安全符合性评审 | | `rule-advisor` | 为不受现有工作流管理的独立任务选择技能 |