team-standards

Use when writing, reviewing, or modifying source code in any language (Java / TypeScript / JavaScript / Dart / Python / Kotlin / Go / Vue / React 等). 跨语言通用编码铁律 7 条 + 注释三档,语言专属 skill (java-coding-standards / korepos-backend-service 等) 在此基础上叠加。MUST 自动触发,不需用户显式要求。

Use when writing, reviewing, or modifying any Java code. You MUST follow these mandatory rules at all times. Apply automatically without being asked. 通用条款见 coding-standards-common；本文件仅列 Java 独占规则（阿里巴巴黄山版强制项的 Java 专属部分）。

Use when the user asks to commit code or generate a commit message AND the staged diff is non-trivial (>2 files, >30 net lines, or contains new/renamed/deleted files). For trivial commits (≤2 files, ≤30 lines, only modifications to existing files) skip this skill and write a clear `git commit` message directly — `hooks/check-git-commit-skill.js` enforces the same threshold at the Bash layer (only blocks `git commit` when staged diff exceeds it). Compose the message from the current session's edit intent first; only re-read diffs to cover gaps. Automatic stage/commit/push applies ONLY to the team-standards plugin source repository, never to business projects that merely install this plugin.

Use BEFORE answering single-service backend questions about table relations / ER / SQL / state transitions / atomic capabilities or project-level technical pain points (subprocess, concurrency, perf, external deps); BEFORE Write/Edit any .md describing such content (anywhere — docs/, ai-docs/, scenarios/, work-log/). Auto-append candidates to `_candidates.md` after investigation discovers reusable facts, or when same tech concern raised ≥3 rounds in one session. Knowledge graph ownership = investigated service, not cwd. Detailed triggers (7 BLOCKING conditions) and scope boundaries listed in `## BLOCKING 强触发清单` section of SKILL.md body.

Use when writing or modifying code that integrates an LLM or builds an agent —— imports langchain4j / spring-ai / openai / anthropic 等 SDK；定义 @Tool / AiService / function-calling 工具；拼装 prompt；解析 LLM 输出。在 coding-standards-common 之上叠加的 LLM/Agent 集成编码铁律：确定性优先、LLM 输出当不可信入参、模糊→结构化用受控枚举、约定单一来源、工具描述是运行时契约、Agent 循环必须兜底、上下文由代码注入。MUST 自动触发，先满足 coding-standards-common 再走本 skill。

当用户要求「架构检查」「lint」「检测架构违规」时触发；当对 Flutter 项目的 presentation/domain/data/infrastructure 层代码执行 Edit/Write 后自动触发一次轻量检查。

You MUST invoke this skill the moment a user reports a bug, describes an error/exception, asks you to investigate or analyze a problem, or mentions writing a bug analysis document. Trigger phrases include: 'there is a bug', 'this is broken', 'why is X happening', 'investigate this issue', 'analyze the root cause', 'we have an OOM/NPE/timeout', 'help me debug'. Invoke BEFORE starting any investigation, root cause analysis, or creating any file under docs/bug/. Pairs with doc-index-required — always invoke that skill too.

Use when applying any bug fix, alignment correction, redundant-code removal, OR adding missing logic to align with upstream/cloud during integration/联调 phase. Trigger when: (1) design-doc-required has routed the change to 「第四·五步：轻量修订流水」 branch, (2) user describes the change as 'fix bug', 'align with cloud/upstream', 'add missing piece', '修 bug', '对齐云端', '删冗余', '修正实现', '改回正确逻辑', '补上漏掉的逻辑', '补缺漏', or (3) about to Edit/Write source code with intent of replacing existing erroneous logic OR adding alignment code that was missed in previous iterations. **注释红线不在本 skill 定义** — 唯一规则源是 coding-standards-common §5.4 + §5.4.1(common 触发顺序早于本 skill,不会漏)。本 skill 只承担 bug 修复期独有的应用层指引:v1.17 方向反转的历史背景、推荐写法 dart 代码示例、摆放位置、适用范围矩阵、遇到存量 [DEPRECATED]/[ADDED] 注释顺手清理的边界、红色警告对照表。

You MUST invoke this skill when a user wants to analyze, document, or understand existing business logic for the purpose of refactoring, rewriting, migration, or regression review. Trigger phrases include: 'analyze current implementation', 'document existing logic', 'I need to understand how X works before refactoring', 'create a knowledge graph for this module', 'map out the business flow', 'help me understand the codebase for refactoring', 'generate a logic orientation doc', 'I want to refactor X, first help me understand it'. Invoke BEFORE any refactoring design or code changes. Pairs with doc-index-required and design-doc-required.

当用户主动纠正 AI 的编码规范错误时（如分层依赖违规、命名不规范、架构约束违反等），必须立即触发本 skill。同时，每次开始编写代码前，必须先读取项目的编码违规记录文档。触发短语：'这样写不对'、'不能引用这个层'、'分层违规'、'改一下依赖方向'、'这个不符合规范'，或用户否定了当前代码写法并给出正确方向时。

当用户要求对**存量**代码做成批注释清理时触发：「清理这个文件/类的注释」「把版本变更注释删掉」「注释太多帮我精简」「按规范清一下注释」「clean up comments」「这文件历史注释清一遍」。专门处理已写好的文件/类/模块里违反注释红线的存量注释（vN 新增 / 变更日志标记 / 历史叙事 prose / 私有方法契约史 / 废话 / 死代码注释），多语言。与 §5.5「改到哪清到哪」的顺手清理、check-comment-density hook 的写入新内容拦截互补——本 skill 是用户主动发起的存量批量对齐。清理红线规则不在本 skill 定义，单一来源是 coding-standards-common §5.4 + §5.4.1，本 skill 只承担存量清理的范围圈定、分类决策、安全边界与提交纪律。

Use to (1) locate code/behavior across ≥2 projects in the kpay POS ecosystem (korepos, korepos-refund, BFF, order-manage, commodity, store-operation-manage, report, price-calc-sdk, pos-config-ts), and (2) register cross-project topology into `kpay-pos-topology/`. MUST trigger when user traces call chains across ≥2 of these projects, mentions ≥2 project names in one question, or is about to Write/Edit markdown referencing ≥2 project names. DO NOT route cross-project mapping/flow into Claude memory, individual project's docs/, or team-standards — only into `kpay-pos-topology/`. Single entry point for cross-project topology knowledge. Detailed trigger phrases and ecosystem project list in SKILL.md body.

每次对业务项目的源码（.dart/.java/.kt/.ts/.py 等）执行 Edit/Write 后、或用户说『记一下工作日志』『记录一下』『写个日志』『更新工作日志』等时，必须触发本 skill 把本次改动按 [Bug 修复] vs [功能开发] 写入用户文档目录 `{USER_DOCUMENTS}/ai-docs/{project}/work-log/{YYYY-MM-DD}.md`（个人工作记录，不入项目仓库）。核心规则：一行一条修改明细、同一 bug 多次修复合并到同一条目、同一功能多轮迭代合并到同一条目、每条目带预估工时（累计）。写入前必须先读当天日志合并现有条目，严禁为同一主题创建多条。每个会话结束前若有未登记的改动，强制回补一次。

Use when writing, reviewing, or modifying any Dart / Flutter code. You MUST follow these mandatory rules at all times. Apply automatically without being asked. 通用条款见 coding-standards-common；本文件仅列 Dart 独占规则（Effective Dart 文档注释 dartdoc 语法 + Dart 专属约定）。korepos / korepos-refund 的 backend 接口代码在本文件之上再叠加 korepos-backend-service。

MUST invoke the instant a user presents any new requirement, feature request, refactoring plan, asks to analyze/evaluate/discuss feasibility, OR requests any code modification — including 'help me change the code' / '帮我改一下' / '按文档实现'. Do NOT wait until code-writing begins. ALSO trigger when about to Edit/Write any source file (.java/.dart/.ts/.py/.kt etc.) without prior invocation. Invoke BEFORE any analysis, planning, or code. Full trigger phrase list and 三档模版分级（极简跳过 / 轻量 / 完整）规则见 SKILL.md body。

Use only for decision-level team-standards changes: adding/removing a Skill, changing a Skill's trigger timing or core behavior, reversing a rule direction, introducing a new template/workflow, changing cross-skill flow structure, or recording a multi-step design decision whose rationale may not be obvious from git history. Do NOT use for ordinary wording tweaks, README/index synchronization, version bumps, typo fixes, or small iterative rule clarifications when the git commit body can carry the rationale.

MUST invoke before creating/writing/editing/moving/renaming ANY AI-generated Markdown — both user knowledge base `{USER_DOCUMENTS}/ai-docs/{project}/` and project `docs/` (v1.20+ 两处索引体系等同)。Phase-A 写前查重 INDEX,Phase-B 写完登记。豁免:索引文件本身(INDEX.md / 00_index.md)、`work-log/` 日期型日志、纯文案不动结构的编辑。详细 Phase-A/B 流程与例外条件见 SKILL.md body。Applies to ALL working directories.

当用户要求「生成项目画像」「生成 project profile」「扫描项目生成 Markdown」时触发。也可被外部平台（如 llm-orchestration-platform）通过指令触发，用于为 AI Agent 生成标准化的项目知识上下文。

Use BEFORE answering questions using domain business terms (订单/账单/退款/分摊/流水/快照/对账 等) AND BEFORE Write/Edit any .md that introduces/relies on business terms. 5 BLOCKING triggers (PRD 含未登记词 / 用户与 AI 同义词错位 / 调查发现新术语 / 用户要求整理 / 场景文档含未登记词) — full list in SKILL.md body. Scope: 业务领域术语 ↔ 代码命名 ↔ 同义词 三方映射;通用技术词汇归 `backend-knowledge-graph-required` 的「技术难点」。与 `init-project-docs/templates/07_glossary.md` 互补——本 skill 会话级日常补登轻量五栏,init 负责项目初始化批量。

当用户要求「初始化项目文档」「生成知识图谱」「分析项目能力」「生成项目文档」时触发。渐进式构建项目知识图谱：Phase 1 核心文档 → Phase 2 映射文档 → Phase 3 流程与术语 → Phase 4 模块深度文档。支持自动模式和人工确认模式。

Use when writing, reviewing, or modifying any Markdown content that contains Mermaid diagrams, complex tables, or structured documentation. You MUST follow these mandatory rules at all times. Apply automatically without being asked. TRIGGER when: generating mermaid code blocks, writing design docs, writing bug docs, creating any .md file with diagrams or structured content; ALSO TRIGGER after completing any structural edit to a Markdown file (新增/删除/重命名 ## 或 ### 章节，或章节移动/合并/重组) to perform TOC review and detect duplicate/scattered/uncategorized sections before marking the file as done.

You MUST invoke this skill after design-doc-required or bug-doc-required completes and a confirmed document exists, but BEFORE writing any implementation code. This is the mandatory bridge between documentation and coding. Trigger: user says 'start implementing', 'now write the code', 'let's begin coding', 'help me modify the code', 'change the code', '帮我修改代码', '改代码', '开始写代码', '帮我改一下', or you are about to make the first code edit (Edit/Write on .java, .dart, .ts, .py, .kt, etc.) for the task. Do NOT write a single line of implementation code until this skill has loaded the code coordinates from the document.

当检测到项目结构变更（新增 Controller/Service/模块/数据库表/API 接口）或用户要求「更新项目文档」「同步知识图谱」时触发。负责识别哪些知识图谱文档需要更新并执行更新。

Use BEFORE answering impact-analysis questions (加这个状态会破坏哪些旧逻辑 / 字段哪里在用 / 事件订阅清单 / API 谁在调) AND BEFORE Write/Edit枚举/状态机/字段/事件 payload/API endpoint 定义类源码。维护 4 类反向索引（states / fields / events / apis）。冷启动用 `hooks/scan-reverse-index.js` 一次性扫描，后续增量。详细 5 类 BLOCKING 触发条件与边界（与 backend-knowledge-graph-required 正向图谱 / cross-project-locator 跨项目调用方互补）见 SKILL.md body 的「触发时机」节。

Use this skill the moment a user proposes a concrete idea, implementation approach, architecture direction, refactor plan, asks Codex to implement a specific solution, or implies that existing code should be copied as the reference pattern. MUST run before design-doc-required planning or code changes when the user's wording contains an assumed solution. Forces Codex to separate the user's real goal from the proposed implementation, evaluate existing-code quality, risks and alternatives, then recommend the best path instead of blindly following the user or copying weak legacy code.