diff --git a/AGENTS.md b/AGENTS.md index cc9fd35..c2bf171 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,7 +26,7 @@ This repo organizes agent rules and knowledge into three layers: - Load: automatic, always in context - Content: hard constraints and safety red lines - Role: quick decisions on what can or cannot be done -- Size control: TSL 47 lines | Python 48 lines | C++ 50 lines | Markdown 23 lines +- Size control: TSL 44 lines | Python 45 lines | C++ 47 lines | Markdown 31 lines ### Layer 2: `codex/skills/` (on-demand, 100-1000 lines per skill) @@ -37,10 +37,7 @@ This repo organizes agent rules and knowledge into three layers: Key skills: - `$tsl-guide` - progressive TSL syntax training (basic/advanced/functions/best practices) -- `$testing-workflow` - cross-language testing strategy -- `$code-review-workflow` - code review workflow - `$commit-message` - commit message convention -- `$create-plan` - create a concise plan - `$style-cleanup` - formatting/style cleanup - `$bulk-refactor-workflow` - safe bulk refactor workflow @@ -61,7 +58,7 @@ Do not load the whole directory. Load only the needed fragments. ### Scenario 1: write a simple TSL function ```text -1. Auto read .agents/tsl/index.md (47 lines) +1. Auto read .agents/tsl/index.md (44 lines) 2. Trigger $tsl-guide, load SKILL.md (192 lines) 3. Generate code @@ -71,7 +68,7 @@ Token cost: ~6,000 tokens ### Scenario 2: write a TSL class ```text -1. Auto read .agents/tsl/index.md (47 lines) +1. Auto read .agents/tsl/index.md (44 lines) 2. Trigger $tsl-guide, load SKILL.md + references/advanced.md 3. Generate code @@ -81,7 +78,7 @@ Token cost: ~10,000 tokens ### Scenario 3: find a TSL function library entry ```text -1. Auto read .agents/tsl/index.md (47 lines) +1. Auto read .agents/tsl/index.md (44 lines) 2. Trigger $tsl-guide, load references/functions_index.md 3. Use rg to locate the function fragment 4. Return the answer @@ -123,7 +120,7 @@ Do: - Add new workflows (e.g., code-review) - Teach a new language from scratch (e.g., tsl-guide) -- Add cross-language common knowledge (e.g., testing-workflow) +- Add cross-language common knowledge (e.g., style-cleanup) --- diff --git a/README.md b/README.md index caf0346..fd15f36 100644 --- a/README.md +++ b/README.md @@ -95,8 +95,9 @@ Layer 1: rulesets/ (≤50 行/语言，模板源) Layer 2: codex/skills/ (按需加载，$skill-name 触发) ├─ tsl-guide: TSL 渐进式语法教学（962 行） - ├─ testing-workflow: 跨语言测试策略 - └─ code-review-workflow: 结构化代码评审 + ├─ commit-message: 提交信息规范 + ├─ style-cleanup: 代码风格整理 + └─ bulk-refactor-workflow: 批量重构流程 Layer 3: docs/ (权威静态文档) └─ 完整语法手册/代码风格/工具链配置 @@ -105,10 +106,10 @@ Layer 3: docs/ (权威静态文档) **目录结构**： - `rulesets/index.md`：规则集索引（跨语言） -- `rulesets/tsl/index.md`：TSL 核心约定（47 行） -- `rulesets/cpp/index.md`：C++ 核心约定（50 行） -- `rulesets/python/index.md`：Python 核心约定（48 行） -- `rulesets/markdown/index.md`：Markdown 核心约定（23 行，仅代码格式化） +- `rulesets/tsl/index.md`：TSL 核心约定（44 行） +- `rulesets/cpp/index.md`：C++ 核心约定（47 行） +- `rulesets/python/index.md`：Python 核心约定（45 行） +- `rulesets/markdown/index.md`：Markdown 核心约定（31 行，仅代码格式化） 详见：`AGENTS.md` @@ -119,13 +120,10 @@ Layer 3: docs/ (权威静态文档) **核心 Skills**： - **`$tsl-guide`**：TSL/TSF 语法完整指南（基础/高级/函数库/最佳实践） -- **`$testing-workflow`**：跨语言测试策略 **通用 Skills**： -- `$code-review-workflow`：代码审查流程 - `$commit-message`：提交信息规范 -- `$create-plan`：生成简明计划 - `$style-cleanup`：整理代码风格 - `$bulk-refactor-workflow`：批量重构流程 - 更多见 `SKILLS.md` diff --git a/SKILLS.md b/SKILLS.md index 4c1ca0c..fdbe136 100644 --- a/SKILLS.md +++ b/SKILLS.md @@ -60,7 +60,7 @@ $CODEX_HOME/skills//SKILL.md sh scripts/install_codex_skills.sh -all # 只安装指定 skills -sh scripts/install_codex_skills.sh -skills style-cleanup,code-review-workflow +sh scripts/install_codex_skills.sh -skills style-cleanup,commit-message ``` 如果希望“项目内本地安装”（不污染全局），可用以下方式： @@ -155,16 +155,7 @@ sh docs/standards/playbook/scripts/install_codex_skills.sh -all ### 通用工作流 Skills -- **`testing-workflow`**：跨语言测试策略 - - - 适用：TSL / Python / C++ - - 覆盖：单元测试 / 集成测试 / 回归测试 - - 108 行 - - `commit-message`：基于 staged diff 自动建议提交信息（`:emoji: type(scope): subject`） -- `create-plan`：生成简明计划（适用于用户明确要求规划编码任务） -- `todo-plan`：按模板追加计划到 TODO.md（触发词：plan/计划/TODO/待办；自动合并/拆分） -- `code-review-workflow`：结构化代码评审（正确性/安全/性能/测试） - `style-cleanup`：整理代码风格（优先使用仓库既有 formatter/lint 工具链） - `bulk-refactor-workflow`：批量重构（安全做法 + 验证契约） diff --git a/codex/skills/code-review-workflow/SKILL.md b/codex/skills/code-review-workflow/SKILL.md deleted file mode 100644 index 0c0a67e..0000000 --- a/codex/skills/code-review-workflow/SKILL.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -name: code-review-workflow -description: - "Structured expert code review for TSL/C++/Python diffs or patches. Triggers: - code review, review PR, diff, 评审, 审查, 安全评审, 性能评审." ---- - -# Code Review Workflow - -## When to Use This Skill - -- Review a PR / `git diff` / patch -- Pre-merge quality gate (correctness/security/perf/tests) -- Risky refactor, behavior change, auth/data path changes - -## Inputs (required) - -- Change set: PR link or `git diff ...` output (must include context) -- Goal: expected behavior / acceptance criteria (1–3 sentences) -- Risk level: low|med|high (default: med) -- Verification: test commands / repro steps (if unknown, ask first) - -## Procedure - -1. **Triage** - - - Identify touched areas, public APIs, behavior changes, data/auth paths - - Classify risk (blast radius, rollback difficulty) - -2. **Correctness** - - - Invariants, edge cases, error handling, null/empty, concurrency - - Backward compatibility (inputs/outputs, wire formats, config) - -3. **Security** - - - AuthZ/AuthN boundaries, least privilege - - Input validation, injection surfaces, secrets/log redaction - -4. **Maintainability** - - - Naming/structure/style aligned with Playbook docs - - Complexity hotspots, duplication, clarity of intent - -5. **Performance** - - - Hot paths, algorithmic complexity, allocations/IO, N+1 patterns - -6. **Tests & Verification** - - Map changes → tests; identify missing coverage - - Provide minimal verification plan (commands + expected signals) - -## Review Standards (Playbook as authority) - -- Commit message: `docs/common/commit_message.md` -- TSL: `docs/tsl/code_style.md`, `docs/tsl/naming.md`, `docs/tsl/toolchain.md` -- C++: `docs/cpp/code_style.md`, `docs/cpp/naming.md`, `docs/cpp/toolchain.md` -- Python: `docs/python/style_guide.md`, `docs/python/tooling.md`, - `docs/python/configuration.md` - -## Output Contract (stable) - -- Summary: what changed & why -- Risk: low|med|high + reasoning -- Blockers: must-fix before merge (with file/line references when possible) -- Non-blocking: Major / Minor / Nit -- Questions: missing context / assumptions -- Suggested verification: exact commands + what success looks like -- Optional patch: minimal diff-style suggestions (only when unambiguous) diff --git a/codex/skills/create-plan/SKILL.md b/codex/skills/create-plan/SKILL.md deleted file mode 100644 index 435fcb1..0000000 --- a/codex/skills/create-plan/SKILL.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -name: create-plan -description: - Create a concise plan. Use when a user explicitly asks for a plan related to a - coding task. -metadata: - short-description: Create a plan ---- - -# Create Plan - -## Goal - -Turn a user prompt into a **single, actionable plan** delivered in the final -assistant message. - -## Minimal workflow - -Throughout the entire workflow, operate in read-only mode. Do not write or -update files. - -1. **Scan context quickly** - - - Read `README.md` and any obvious docs (`docs/`, `CONTRIBUTING.md`, - `ARCHITECTURE.md`). - - Skim relevant files (the ones most likely touched). - - Identify constraints (language, frameworks, CI/test commands, deployment - shape). - -2. **Ask follow-ups only if blocking** - - - Ask **at most 1–2 questions**. - - Only ask if you cannot responsibly plan without the answer; prefer - multiple-choice. - - If unsure but not blocked, make a reasonable assumption and proceed. - -3. **Create a plan using the template below** - - - Start with **1 short paragraph** describing the intent and approach. - - Clearly call out what is **in scope** and what is **not in scope** in - short. - - Then provide a **small checklist** of action items (default 6–10 items). - - Each checklist item should be a concrete action and, when helpful, - mention files/commands. - - **Make items atomic and ordered**: discovery → changes → tests → rollout. - - **Verb-first**: “Add…”, “Refactor…”, “Verify…”, “Ship…”. - - Include at least one item for **tests/validation** and one for **edge - cases/risk** when applicable. - - If there are unknowns, include a tiny **Open questions** section (max 3). - -4. **Do not preface the plan with meta explanations; output only the plan as per - template** - -## Plan template (follow exactly) - -```markdown -# Plan - -<1–3 sentences: what we’re doing, why, and the high-level approach.> - -## Scope - -- In: -- Out: - -## Action items - -[ ] [ ] [ ] [ ] [ ] [ ] - -## Open questions - -- -- -- -``` - -## Checklist item guidance - -Good checklist items: - -- Point to likely files/modules: src/..., app/..., services/... -- Name concrete validation: “Run npm test”, “Add unit tests for X” -- Include safe rollout when relevant: feature flag, migration plan, rollback - note - -Avoid: - -- Vague steps (“handle backend”, “do auth”) -- Too many micro-steps -- Writing code snippets (keep the plan implementation-agnostic) diff --git a/codex/skills/testing-workflow/SKILL.md b/codex/skills/testing-workflow/SKILL.md deleted file mode 100644 index 202bef0..0000000 --- a/codex/skills/testing-workflow/SKILL.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -name: testing-workflow -description: "测试策略与最佳实践（TSL/Python/C++）：单元测试→集成测试→回归测试。Triggers: 写测试, 测试策略, 单元测试, 集成测试, testing, unit test, how to test" ---- - -# 测试工作流 - -> 适用语言：TSL / Python / C++ -> 核心原则：新功能与 bug 修复必须有可复现的测试。 - -## 使用时机 - -- 新功能开发 -- Bug 修复 -- 重构或行为变更 - -## 测试层级 - -### 1. 单元测试（Unit Tests） - -**目标**：验证单个函数/类的行为 - -- 测试纯函数（无副作用） -- Mock 外部依赖（文件/网络/数据库） -- 一个测试只验证一个行为点 - -**命名示例**： - -- `test_add_positive_numbers_returns_sum` -- `test_add_with_zero_returns_other_number` - -### 2. 集成测试（Integration Tests） - -**目标**：验证模块间交互 - -- 关键流程的 end-to-end 测试 -- 使用真实依赖或测试环境 -- 验证数据流与状态转换 - -### 3. 回归测试（Regression Tests） - -**目标**：防止已修复的 bug 复发 - -- 修 bug 先写失败测试 -- 修复后测试通过 - -## 何时补测试 - -| 场景 | 是否需要测试 | 测试类型 | -| --------- | ------------ | ------------ | -| 新功能 | ✅ 必须 | 单元 + 集成 | -| Bug 修复 | ✅ 必须 | 回归 | -| 重构 | ✅ 必须 | 运行现有测试 | -| 文档/注释 | ❌ 不需要 | - | -| 格式调整 | ❌ 不需要 | - | - -## 测试可维护性原则 - -1. 一个测试一个断言（或一组相关断言） -2. 测试名称自解释 -3. 避免依赖外部资源（用 Mock/Stub） -4. 测试代码也要可读 - -## 反模式 - -- 依赖执行顺序、随机数、系统时间 -- 单元测试过慢（>1s） -- Magic number 过多 -- 重复测试相同行为 - -## 运行测试 - -### TSL - -- 若项目已有测试命令，优先使用项目标准命令 -- 否则建议添加最小可运行脚本并在 README 说明 - -### Python - -```bash -pytest tests/ -pytest tests/test_module.py::test_function -``` - -### C++ - -```bash -ctest -./build/test_runner --gtest_filter=TestSuite.TestName -``` - -## 测试失败处理 - -1. 定位：哪个测试失败、失败条件是什么 -2. 复现：单独运行失败用例 -3. 调试：优先检查本次改动 -4. 无关失败：记录并告知用户 - -## 可选：测试驱动开发（TDD） - -1. Red：先写失败测试 -2. Green：写最少代码让测试通过 -3. Refactor：重构保持测试绿色 - -## 权威参考 - -- TSL：`docs/tsl/` 测试相关文档（如有） -- Python：`docs/python/tooling.md` -- C++：`docs/cpp/toolchain.md` diff --git a/codex/skills/todo-plan/SKILL.md b/codex/skills/todo-plan/SKILL.md deleted file mode 100644 index e83e18f..0000000 --- a/codex/skills/todo-plan/SKILL.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -name: todo-plan -description: "Create and append plan blocks to TODO.md when the user asks for a plan or mentions plan/计划/TODO/待办; auto-merge or split related tasks." ---- - -# TODO Plan Writer - -## Trigger guard - -- Only run if the user message explicitly contains one of: `plan`, `计划`, `TODO`, `待办`. - -## Output target - -- Append plan blocks to `TODO.md` (at file end). -- Do not modify other files. - -## Planning rules - -- Use create-plan style reasoning: intent -> scope -> action items; include validation/risks when relevant. -- Title: concise "module + action" (2-6 words or 6-12 chars). -- Multiple tasks: - - Merge into one Plan if same module/goal. - - Split if different modules/goals. - -## Formatting rules - -- Use the template below verbatim. -- Always keep a blank line after the `## Plan: ...` header. -- Keep existing TODO.md English structure and indentation. -- Use `[ ]` for each action item line. -- If notes are not obvious, use `- TBD`. -- Line endings: LF. - -## Plan template - -```md -## Plan: - -- Goal: <one-line objective> -- Scope: - - In: <what is included> - - Out: <what is excluded> -- Actions: - [ ] <action item> - [ ] <action item> -- Notes: - - <tests / observations / constraints> -``` diff --git a/rulesets/cpp/index.md b/rulesets/cpp/index.md index cbb89b8..3d8409e 100644 --- a/rulesets/cpp/index.md +++ b/rulesets/cpp/index.md @@ -39,8 +39,6 @@ ## Skills（按需加载） -- `$testing-workflow` -- `$code-review-workflow` - `$commit-message` ## 与开发规范的关系 diff --git a/rulesets/python/index.md b/rulesets/python/index.md index 3504194..96fc9e8 100644 --- a/rulesets/python/index.md +++ b/rulesets/python/index.md @@ -37,8 +37,6 @@ ## Skills（按需加载） -- `$testing-workflow` -- `$code-review-workflow` - `$commit-message` ## 与开发规范的关系 diff --git a/rulesets/tsl/index.md b/rulesets/tsl/index.md index 92460d4..65f1dc8 100644 --- a/rulesets/tsl/index.md +++ b/rulesets/tsl/index.md @@ -36,8 +36,6 @@ ## Skills（按需加载） - `$tsl-guide` -- `$testing-workflow` -- `$code-review-workflow` - `$commit-message` ## 与开发规范的关系 diff --git a/scripts/install_codex_skills.bat b/scripts/install_codex_skills.bat index 7703785..699d0f2 100644 --- a/scripts/install_codex_skills.bat +++ b/scripts/install_codex_skills.bat @@ -7,7 +7,7 @@ rem - Dest: %CODEX_HOME%\skills\<skill-name>\ (default CODEX_HOME=%USERPROFIL rem rem Usage: rem install_codex_skills.bat -all -rem install_codex_skills.bat -skills style-cleanup,code-review-workflow +rem install_codex_skills.bat -skills style-cleanup,commit-message rem install_codex_skills.bat -local -all rem rem Notes: @@ -94,7 +94,7 @@ exit /b 0 :show_help echo Usage: echo install_codex_skills.bat -all -echo install_codex_skills.bat -skills style-cleanup,code-review-workflow +echo install_codex_skills.bat -skills style-cleanup,commit-message echo. echo Options: echo -local, -l Install to .\\.codex ^(or CODEX_HOME if set^) diff --git a/scripts/install_codex_skills.ps1 b/scripts/install_codex_skills.ps1 index 39947b2..ee2c188 100644 --- a/scripts/install_codex_skills.ps1 +++ b/scripts/install_codex_skills.ps1 @@ -4,7 +4,7 @@ # # Usage: # powershell -File scripts/install_codex_skills.ps1 -# powershell -File scripts/install_codex_skills.ps1 style-cleanup code-review-workflow +# powershell -File scripts/install_codex_skills.ps1 style-cleanup commit-message # powershell -File scripts/install_codex_skills.ps1 -Local # # Notes: @@ -27,7 +27,7 @@ $ErrorActionPreference = "Stop" if ($Help) { Write-Host "Usage:" Write-Host " powershell -File scripts/install_codex_skills.ps1 -All" - Write-Host " powershell -File scripts/install_codex_skills.ps1 -Skills style-cleanup,code-review-workflow" + Write-Host " powershell -File scripts/install_codex_skills.ps1 -Skills style-cleanup,commit-message" Write-Host "" Write-Host "Options:" Write-Host " -Local Install to ./.codex (or CODEX_HOME if set)." diff --git a/scripts/install_codex_skills.sh b/scripts/install_codex_skills.sh index 3874955..d4364c5 100644 --- a/scripts/install_codex_skills.sh +++ b/scripts/install_codex_skills.sh @@ -7,7 +7,7 @@ set -eu # # Usage: # sh scripts/install_codex_skills.sh -all -# sh scripts/install_codex_skills.sh -skills style-cleanup,code-review-workflow +# sh scripts/install_codex_skills.sh -skills style-cleanup,commit-message # sh scripts/install_codex_skills.sh -local -all # install to <cwd>/.codex # # Notes: @@ -22,7 +22,7 @@ usage() { cat <<'EOF' >&2 Usage: sh scripts/install_codex_skills.sh [options] - sh scripts/install_codex_skills.sh -skills style-cleanup,code-review-workflow + sh scripts/install_codex_skills.sh -skills style-cleanup,commit-message sh scripts/install_codex_skills.sh -all Options: