0
代码
代码
Issues
Pull Requests
讨论
Wiki
分析
0
Aaflyingtofix(skills): update all gitcode CLI commands based on schema verification
934c63ec创建于 8 天前历史提交

AI Dev Workflow — 项目空间约束

本工作区是多仓开发工作区，不是单一代码仓。

本文件是项目级 system prompt，作用：(1) 约束工作区目录读取范围；(2) 定义开发工作流的核心约束。详细操作步骤、Artifact 模板、各阶段执行清单、独立能力调用时机等都在 gitcode-dev-workflow skill 里——开始任何新需求时优先触发该 skill。

工作区结构

<workspace>/
├── AGENTS.md                       # 本文件，最高优先级约束
├── .agents/skills/                 # 项目级 skill（gitcode-* + superpowers）
├── ai-dev-workflow/                # AI 开发流程框架仓（仅首次初始化用，之后不必读）
├── specs/                          # 归档文档仓（固定存在，非业务代码仓）
└── <repo-name>/                    # 业务代码仓，按需拉取，0 个或多个

specs 沉淀跨仓系统设计、需求/接口/安全设计、测试策略、发布报告和 AI Spec：

specs/
├── architecture_design/
├── spec/<repo-name>/{system_design,task_design,ai_memory.md}
├── issue_docs/<repo-name>/
├── test_docs/
└── release_docs/<repo-name>/

上下文加载原则

AI 开始任务时，先从用户请求识别目标仓 <repo-name> 和需求范围。默认只加载：

  1. <repo-name>/
  2. specs/spec/<repo-name>/（先看 ai_memory.md，再看 system_design/、task_design/<需求目录>/）
  3. specs/issue_docs/<repo-name>/
  4. specs/release_docs/<repo-name>/

按需补充（沿索引读取，不要无差别遍历）：

场景 补充读取
系统边界 / 接口 / 数据模型 / 安全 / 部署 specs/architecture_design/、spec/<repo>/system_design/
测试策略 / 验收 / 质量证明 specs/test_docs/（按仓名/需求名/迭代检索）
跨仓影响 先明确受影响仓集合，再分别按上面 4 项展开，不要默认扫描全部仓

检索优先用 rg "<keyword>" <target-dir> 而非全量读取；优先看 README/索引/设计/任务文档，再看源码细节。

AI 行为约束

  • 不要把 specs 当作业务代码仓。
  • 未识别目标仓前，不要全量扫描所有目录。
  • 不要把其他仓的规则套用到当前仓，除非文档明确说明是跨仓通用规则。
  • 需求文档与代码实现冲突时，指出冲突并以当前代码为准继续核实。
  • 默认只允许修改用户指定的 <repo-name> 与 specs；扩大范围前必须获得用户同意。
  • 当前项目的运行环境都在 Windows，必须使用 GitCode CLI 的 Windows 版命令，即调用 gitcode（不是 gc，gc 是 PowerShell 的 Get-Content 内置别名）。

🚨 开发工作流核心约束（覆盖所有其他偏好）

以下规则用于约束 AI 开发主流程。详细操作步骤、Artifact 模板、各 Phase 执行清单见 gitcode-dev-workflow skill。

必须遵守的硬规则

  • 开始任何新需求时，必须先确定流程模式：Full / Standard / Light。
  • 如果用户明确指定流程模式，直接采用用户指定模式。
  • 如果用户没有指定流程模式，AI 必须自行判断并向用户说明推荐模式、判断依据、会执行/跳过的关键环节，获得用户确认后才能进入开发。
  • 所有业务 PR 必须关联业务 Issue。没有现成 Issue 时，必须通过 gitcode issue create 创建。
  • 所有 GitCode 远端写操作（issue / pr / comment / review / release）必须通过 gitcode CLI。禁止改用 REST API、网页操作或其他工具。
  • 所有由 AI 创建的 PR（业务仓 + specs 仓）必须打上 ai-assisted 标签（gitcode pr create 无 --label 参数，创建后需执行 gitcode pr edit <n> --labels ai-assisted 补打）。该标签已在项目内预先创建，AI 不要重复创建。
  • AI 每轮完成代码修改并交付给用户时，必须提交一次 commit。commit 粒度是一轮 AI 编码交付，不是每个原子任务。
  • Phase 4 业务 PR 只能在用户自测并确认完成后执行。用户自测/反馈循环发生在 PR 创建之前。
  • Phase 5 最终归档只能由用户明确触发。业务 PR 完成或合入后，才允许进入归档。
  • 业务仓 PR 不允许带 spec 文件。spec artifact 必须归档到 specs 仓并通过 PR 提交，不允许直接 push docs 主干。

流程模式判定

判断因素 Light Standard Full
改动规模 约 30 行以内 约 30-300 行 超过 300 行或难以估算
仓库范围 单仓 单仓 跨仓
模块范围 单文件/单点 单模块/少量文件 跨模块
接口变化 无 通常无，或仅内部接口 有外部接口/契约变化
数据模型 无 通常无 有 schema / 数据结构 / 迁移
安全影响 无 低 涉及鉴权、权限、输入、凭证、依赖
部署/发布影响 无 低 有部署、配置、发布链路影响
测试要求 最小验证 相关测试 完整测试策略
文档要求 Issue/PR 描述即可 简版 proposal/tasks 完整 proposal/design/tasks

边界情形：行数小但触及鉴权/接口/数据，应升级；详细判定与对话模板见 skill。

主流程与闸门（简表）

Phase 目标 必须出示的闸门证据
Phase 0 上下文加载 识别目标仓 + 选模式 目标仓 + 当前分支 + 已加载上下文 + 推荐模式 + 用户确认
Phase 1 Issue 与需求确认 关联/创建业务 Issue 业务 Issue URL + 用户确认的需求范围
Phase 2 轻量设计与计划 实现计划 + 生成前约束 修改文件清单 + 验证方式 + 用户确认
Phase 3 AI 编码交付 一轮代码 + commit commit hash + 验证结果 + 自检结果
用户自测/反馈循环 用户验收 用户明确确认完成（模糊信号要追问）
Phase 4 业务 PR 交付 业务 PR PR URL + ai-assisted 标签 + 关联 Issue
Phase 5 最终归档 沉淀经验（用户触发） docs PR URL（含 archive.md） + 业务 Issue 状态正确

各 Phase 的详细步骤、按模式执行清单、Artifact 模板都在 gitcode-dev-workflow skill。

独立触发能力（不属于主流程强制卡点）

以下能力只在用户明确要求或任务本身明确触发时执行，不要把它们当成 Phase 3/4 的强制环节：

能力 Skill 典型触发
质量检查（build/test/cov 等） gitcode-dev-quality 用户要求"质量检查 / 提交前检查 / lint / 覆盖率"
安全审查 gitcode-security-check 用户要求安全检查，或改动涉及鉴权/输入/凭证/依赖
PR 审查 gitcode-pr-review 用户要求审 PR / 代码评审
流水线分析 gitcode-pipeline-analyzer 用户要求看流水线，或 PR CI 失败

分支隔离（强制）

开始任何代码修改前，必须先 git branch --show-current 检查当前分支。禁止在 master/main 直接修改代码。

分支命名：

# 业务仓
git checkout -b fix/<description>          # bug 修复
git checkout -b feat/<description>         # 新功能

# specs 仓
git checkout -b spec/<repo-name>/<change-name>

子代理启动时必须传入当前分支名，子代理不得切换分支、不得修改超出任务描述的文件。

Artifact 文件归档（强制）

spec artifact 落盘到 specs 仓：

specs/spec/<repo-name>/task_design/<change-name>/
├── proposal.md     # 需求背景 + 验收标准（Phase 1）
├── design.md       # 技术方案 + 影响范围（Phase 1，无新决策可省略）
├── tasks.md        # 实现步骤 checkbox（Phase 2）
└── archive.md      # 最终归档（Phase 5）

可复用经验沉淀到 specs/spec/<repo-name>/ai_memory.md（仅沉淀经过验证且会复用的规则）。

Light 模式通常不强制落盘；模板与最小版本见 skill。

specs 仓归档约束：

  1. 业务仓开发过程产生的 spec 交付文档不允许纳入业务仓 PR 提交范围。
  2. spec/archive 文档必须归档到独立的 specs 仓，且遵守其目录结构。
  3. 文档归档必须通过 PR 提交到主干分支（master/main），不允许直接 push。
  4. 归档时机：Phase 3 后先进入用户自测/反馈循环 → 用户确认完成 → Phase 4 业务 PR → 业务 PR 完成或合入后 → 用户触发 Phase 5 统一归档。
分支名:    spec/<repo-name>/<change-name>
PR 标题:   docs(spec/<repo-name>): <change-name>
PR 描述:   关联业务仓 issue（跨仓引用 <owner>/<repo>#<n>）+ 变更摘要

引用 spec 文件时使用 GitCode permalink（commit SHA URL），避免分支删除后 URL 失效。

质量门禁（插槽式）

以下槽位由业务仓 AGENTS.md 填充具体命令。未填充的槽位跳过。

槽位 用途 业务仓填充示例
build 编译构建 mvn compile -q / pip install -e . / npm run build
test 运行测试 mvn test / pytest / npm test
coverage 覆盖率检查 mvn jacoco:report / pytest --cov / npm run coverage
format 代码格式化 mvn checkstyle:check / ruff check / npm run lint
static 静态分析 无新 TODO/FIXME / ruff / eslint
security 安全检查 gitcode-security-check

业务仓 AGENTS.md 必须包含"质量门禁命令"小节，按实际技术栈填充上表。

Commit 规范（强制）

每轮 AI 编码交付提交一次，单 commit 对应一轮 AI 编码交付。用户自测反馈后每轮修改也必须新 commit（不要 amend）。

<type>(<scope>): <summary in present tense, ≤72 chars>

<body: what changed and why, reference issues if applicable>

Co-authored-by: <Tool / Agent Name> <noreply@tool-provider.com>
Generated-by: <underlying-model-id>

字段约束：

字段 约束
<type> feat / fix / docs / refactor / test / chore / perf / build / ci
<scope> 模块名 / 包名 / 子系统（如 auth、core；specs 仓用 spec/<repo-name>）
summary 现在时祈使式，≤72 字符，不以句号结尾
body 改了什么 + 为什么；关联 issue 用 Refs #<n> 或 Fixes #<n>；body 与 trailers 之间空 1 行
Co-authored-by AI 工具名 + provider 邮箱（例：Trae <noreply@trae.ai>、Claude Code <noreply@anthropic.com>、Cursor <noreply@cursor.com>）
Generated-by 底层模型 ID（例：claude-opus-4-7、claude-sonnet-4-6、gpt-5-codex）

GitCode 远端交互（强制）

所有 GitCode 远端写操作必须通过 gitcode CLI。高频命令：

操作 命令
创建 Issue gitcode issue create -R <owner/repo> --title <t> --body-file <f> --label <labels>
评论 Issue gitcode issue comment <n> -R <owner/repo> --body-file <f>
创建 PR gitcode pr create -R <owner/repo> --title <t> --body-file <f> --base <branch>
PR 补打标签 gitcode pr edit <n> -R <owner/repo> --labels ai-assisted
编辑 PR body（中文） gitcode pr edit <n> -R <owner/repo> --body-file <f>
评论 PR gitcode pr comment <n> -R <owner/repo> --body-file <f>
PR 行内评论 gitcode pr comment <n> -R <owner/repo> --body <text> --path <file> --position <n>
PR 审查 gitcode pr review <n> -R <owner/repo> --approve --comment-file <f>
合并 PR gitcode pr merge <n> -R <owner/repo> --method <merge/squash/rebase> --yes
跨仓引用 issue/PR body 中用 <owner>/<repo>#<n> 语法

凭证：依赖 Windows 用户级永久环境变量 GC_TOKEN。若 gitcode auth status 报未登录，立即停止并要求用户重新提供 token，禁止自行猜测或绕过。

Windows 中文编码（强制踩坑预防）

PowerShell 默认编码与 UTF-8 不一致，直接用 --body 传中文会乱码。所有含中文的远端写操作必须用 --body-file + 显式 UTF-8 写盘：

[System.IO.File]::WriteAllText("$env:TEMP\comment.md", $bodyContent, [System.Text.Encoding]::UTF8)
gitcode issue comment <n> --body-file "$env:TEMP\comment.md"

禁止：

  • 用 --body 直接传中文变量。
  • 用 Get-Content -Raw 读中文文件后再传 --body。
  • 用 Set-Content / Out-File 默认编码写文件（不是 UTF-8）。

特例：gitcode pr create 不支持 --labels。创建后需用 gitcode pr edit <n> --labels ai-assisted 补打标签。--body-file 已支持，含中文 PR 描述可直接 --body-file 一步到位。

生成前约束检查

requesting-code-review 不作为主流程环节。AI 在编码前必须把审查要求转化为生成约束，并在交付前自检：

  • 是否只修改用户指定业务仓和允许的 specs 范围。
  • 是否遵循目标仓既有架构、命名、错误处理、日志、配置和测试风格。
  • 是否避免无关重构、无关格式化和元数据 churn。
  • 是否存在硬编码凭证、敏感信息、危险默认值或明显注入风险。
  • 是否为行为变化提供了匹配的测试或说明了不可测原因。

TDD / 测试要求（按模式）

模式 要求
Full 有行为变化时优先 RED → GREEN → REFACTOR，并执行完整测试策略
Standard 有行为变化时必须补充或更新相关测试，并运行相关验证
Light 有行为变化且可测时补充最小测试；文案/注释/无行为配置改动可说明原因后跳过

关联资源

  • 详细工作流 playbook：gitcode-dev-workflow skill（.agents/skills/gitcode-dev-workflow/SKILL.md）
  • 初始化 Playbook：ai-dev-workflow/README.md
  • 完整交付规范：ai-dev-workflow/AI-DELIVERY-WORKFLOW.md