accelint-onboard-agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Onboard Agents

接入Agents

Guide the user through a conversational interview to produce a complete, project-specific

AGENTS.md

(or

CLAUDE.md

) governing how an AI coding agent behaves across all interactions in the project.

引导用户完成对话式访谈，生成完整的、适配具体项目的

AGENTS.md

（或

CLAUDE.md

）文件，用于规范AI编码Agent在项目所有交互中的行为。

Separation of Concerns

关注点分离

This skill produces the behavior layer of the agent instruction stack. It is the companion to the

accelint-onboard-openspec

skill, which produces the project DNA layer (

openspec/config.yaml

). They never duplicate each other.

┌──────────────────────────────────────────────────────────────┐
│                    Agent Instruction Stack                   │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  AGENTS.md / CLAUDE.md   ← THIS SKILL                        │
│  ─────────────────────   (Layer 1: Agent Identity)           │
│  WHO the agent is, HOW it works, WHEN it communicates        │
│                                                              │
│  • Role definition                                           │
│  • Communication style and tone                              │
│  • Workflow procedures (PR flow, commit conventions)         │
│  • Decision-making heuristics                                │
│  • Tool usage preferences                                    │
│  • Behavioral guardrails                                     │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  openspec/config.yaml    ← accelint-onboard-openspec skill   │
│  ────────────────────    (Layer 2: Project DNA)              │
│  WHAT the project is, WHAT stack it uses, WHAT rules apply   │
│                                                              │
│  • Domain description and tech stack                         │
│  • Architectural patterns and coding standards               │
│  • Project structure and per-artifact rules                  │
│                                                              │
└──────────────────────────────────────────────────────────────┘

此技能生成Agent指令栈的行为层，是

accelint-onboard-openspec

技能的配套工具，后者负责生成项目DNA层（

openspec/config.yaml

），二者内容完全不重复。

┌──────────────────────────────────────────────────────────────┐
│                    Agent Instruction Stack                   │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  AGENTS.md / CLAUDE.md   ← 本技能生成内容                        │
│  ─────────────────────   (第1层: Agent身份)                     │
│  Agent角色定位、工作方式、沟通触发规则                            │
│                                                              │
│  • 角色定义                                           │
│  • 沟通风格与语气                              │
│  • 工作流程规范（PR流程、提交规范）         │
│  • 决策规则                                │
│  • 工具使用偏好                                    │
│  • 行为护栏                                     │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  openspec/config.yaml    ← accelint-onboard-openspec 技能生成内容   │
│  ────────────────────    (第2层: 项目DNA)              │
│  项目定位、技术栈、适用规则   │
│                                                              │
│  • 领域描述与技术栈                         │
│  • 架构模式与编码标准               │
│  • 项目结构与单文件规则                  │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Hard Rule: What Does NOT Belong Here

硬性规则：不属于本文件的内容

If a piece of information answers "what is the project?" rather than "how should the agent behave?", it belongs in

config.yaml

, not here.

Belongs in AGENTS.md	Belongs in config.yaml
"Always run `pnpm check` before committing"	"Package manager: pnpm"
"Use Conventional Commits"	"TypeScript 5.x, strict mode"
"Ask before deleting files"	"Monorepo: Turborepo + PNPM"
"Prefer small, focused PRs"	" `type` over `interface` "
"You are a senior TS engineer"	"Domain: geospatial visualization"
"Never force-push to main"	"Testing: Vitest + @testing-library"

如果某条信息回答的是"项目是什么"而非"Agent应该如何表现"，那么它应该放在

config.yaml

中，而非本文件。

属于AGENTS.md的内容	属于config.yaml的内容
"提交前必须运行 `pnpm check` "	"包管理器: pnpm"
"使用Conventional Commits规范"	"TypeScript 5.x，严格模式"
"删除文件前先询问"	"Monorepo: Turborepo + PNPM"
"优先提交小而聚焦的PR"	"优先使用 `type` 而非 `interface` "
"你是高级TS工程师"	"领域：地理空间可视化"
"永远不要强制推送main分支"	"测试：Vitest + @testing-library"

Phases

执行阶段

Phase 0 — File State Detection

阶段0 — 文件状态检测

Before any interview question is asked, check whether the target file exists and assess its state. Never silently pick a mode — always announce the detected mode to the user and confirm before proceeding.

Detection logic:

Does AGENTS.md (or CLAUDE.md) exist?
│
├── No → MODE 1: Create
│         Full interview from scratch.
│
└── Yes → Read the file, then assess:
          │
          ├── Empty or near-blank (< ~10 meaningful lines)?
          │     → MODE 1: Create (with overwrite confirmation)
          │       Ask: "AGENTS.md exists but appears empty — should I
          │       populate it from scratch, or preserve any current content?"
          │
          ├── Contains recognised template sections?
          │   (## Role & Identity, ## Guardrails, ## Workflow Procedures, etc.)
          │     → MODE 3: Refresh
          │       Abbreviated interview covering only detected drift and
          │       unresolved <!-- TODO --> markers.
          │
          └── Contains real content in an unrecognised shape?
                → MODE 2: Import
                  Present three options (A / B / C) before proceeding.

Recognised template sections (any two or more = recognised shape):

## Role & Identity

## Communication

## Workflow Procedures

## Decision Heuristics

## Tool Preferences

## Guardrails

在提出任何访谈问题前，先检查目标文件是否存在并评估其状态。永远不要静默选择模式，始终向用户告知检测到的模式并确认后再继续。

检测逻辑：

AGENTS.md（或CLAUDE.md）是否存在？
│
├── 不存在 → 模式1：新建
│         从零开始完成完整访谈。
│
└── 存在 → 读取文件后评估：
          │
          ├── 为空或接近空白（有效行数<10行）？
          │     → 模式1：新建（需确认是否覆盖）
          │       询问："AGENTS.md已存在但内容为空，我应该从零开始填充内容，还是保留当前已有内容？"
          │
          ├── 包含可识别的模板章节？
          │   （## 角色与身份、## 护栏、## 工作流程规范等）
          │     → 模式3：更新
          │       简化访谈，仅覆盖检测到的内容偏差和未解决的<!-- TODO -->标记。
          │
          └── 包含实际内容但格式不可识别？
                → 模式2：导入
                  继续操作前先提供三个选项（A/B/C）供用户选择。

可识别的模板章节（出现任意2个及以上即为可识别格式）：

## Role & Identity

## Communication

## Workflow Procedures

## Decision Heuristics

## Tool Preferences

## Guardrails

Mode 1: Create

模式1：新建

Run the full Phase 1 → Phase 2 → Phase 3 → Phase 4 interview. This is the happy path for a fresh repo.

按完整流程执行阶段1→阶段2→阶段3→阶段4访谈，这是新仓库的最优路径。

Mode 2: Import

模式2：导入

The file has real content that was not generated by this skill. Present the user with three options before touching anything:

"This AGENTS.md has existing content with a structure I don't recognise. How would you like to proceed?
(a) Restructure — I'll import your existing content, map it onto this skill's template sections, flag any material that belongs in
openspec/config.yaml
instead, run a targeted interview to fill gaps, and produce a merged file ready to replace the current one.
(b) Append — I'll run the full interview and add this skill's sections below your existing content without modifying what's already there.

(c) Dry run — I'll run the full interview and show you exactly what I would have generated, with no changes to the filesystem. Use this to evaluate fit before committing."

If option (a) is chosen:

Read the file in full.
Map each existing section onto the skill's template sections.
Flag any content that violates the separation-of-concerns boundary (e.g., stack facts, tech versions, domain descriptions) — these belong in
```
openspec/config.yaml
```
. For each violation, ask: "This describes [X] — that's project DNA and belongs in
config.yaml
. Should I move it there and leave a reference here?"
Run a targeted interview covering only the gaps (sections with no existing coverage).
Show a merged preview before writing. Inferred/existing content is labelled
```
# from existing file
```
; new content is labelled
```
# new
```
.

If option (b) is chosen: Run the full Phase 1 → Phase 4 interview and append the generated sections below a

---

divider and a comment:

<!-- Added by accelint-onboard-agents skill -->

If option (c) is chosen: Run the full Phase 1 → Phase 4 interview and present the output in the conversation. Explicitly state: "No files were changed." Offer to re-run as (a) or (b) if the user is satisfied.

文件包含非本技能生成的实际内容，修改任何内容前先向用户提供三个选项：

"此AGENTS.md已有内容，但结构我无法识别。你希望如何继续？
(a) 重构 — 我会导入现有内容，映射到本技能的模板章节中，标记出应该放在
openspec/config.yaml
的内容，通过定向访谈补全空缺，最终生成合并后的文件替换当前文件。
(b) 追加 — 我会完成完整访谈，将本技能生成的章节添加到现有内容下方，不修改已有内容。

(c) 试运行 — 我会完成完整访谈，向你展示将生成的内容，不会修改文件系统。你可以在确认适用后再选择正式执行。"

如果选择选项(a)：

完整读取文件内容。
将每个现有章节映射到本技能的模板章节中。
标记所有违反关注点分离边界的内容（例如技术栈信息、版本号、领域描述）——这些内容应该放在
```
openspec/config.yaml
```
中。对每个违规内容询问："此内容描述的是[X]，属于项目DNA，应该放在
config.yaml
中。我是否应该将其移动到该文件并在此处留下引用？"
仅针对空缺章节（没有现有内容覆盖的部分）进行定向访谈。
写入前展示合并预览，推断/现有内容标记为
```
# 来自现有文件
```
，新内容标记为
```
# 新增
```
。

如果选择选项(b)： 执行完整的阶段1→阶段4访谈，将生成的章节添加到

---

分隔线和注释

<!-- Added by accelint-onboard-agents skill -->

下方。

如果选择选项(c)： 执行完整的阶段1→阶段4访谈，在对话中展示输出内容，明确告知："未修改任何文件。"如果用户满意，可以提供重新以(a)或(b)模式运行的选项。

Mode 3: Refresh

模式3：更新

The file matches the skill's expected shape — it was likely produced by a previous run. Run an abbreviated interview covering only:

Drift detection — scan the codebase for changes since the file was last updated:

Signal	Where to look
New packages added	`package.json` , workspace `package.json` files
CI checks changed	`.github/workflows/` — new required gates?
Husky hooks modified	`.husky/` — new pre-commit steps?
New migration directory	`migrations/` , `prisma/migrations/` , `alembic/`
Versioning tooling added	`.changeset/` , `.releaserc*`
OpenSpec added/removed	`openspec/` directory presence
New protected branches	`.github/branch-protection*` , README

Unresolved TODOs — find all
```

```
markers left from the previous run and surface them as targeted questions.
Announce findings before asking anything:

"I found [N] sections that may have drifted and [M] unresolved TODOs. I'll only ask about those — the rest looks current."
After the targeted interview, show a diff-style preview (changed sections only) before writing. Do not re-emit sections that have not changed.

文件符合本技能的预期格式——很可能是之前运行生成的。仅针对以下内容执行简化访谈：

偏差检测 — 扫描代码库中自文件上次更新以来的变更：

信号	检测位置
新增依赖包	`package.json` 、工作区 `package.json` 文件
CI检查变更	`.github/workflows/` — 是否有新的强制卡点？
Husky钩子修改	`.husky/` — 是否有新的预提交步骤？
新增迁移目录	`migrations/` 、 `prisma/migrations/` 、 `alembic/`
新增版本管理工具	`.changeset/` 、 `.releaserc*`
OpenSpec新增/移除	`openspec/` 目录是否存在
新增保护分支	`.github/branch-protection*` 、README

未解决的TODO — 查找上次运行留下的所有
```

```
标记，作为定向问题提出。
提问前先告知发现结果：

"我发现有[N]个章节可能存在内容偏差，还有[M]个未解决的TODO。我只会询问这些内容，其余部分看起来都是最新的。"
定向访谈完成后，写入前仅展示变更部分的差异预览，不会重新输出未变更的章节。

Phase 1 — Discovery Interview

阶段1 — 调研访谈

Run the interview conversationally. Don't dump all questions at once. Group them into natural topic turns. If the user describes a workflow, infer related behavioral constraints and confirm rather than asking again.

Turn 1 — Role & Identity

What role should the agent play? ("senior TypeScript engineer", "full-stack developer", "pair programmer", "code reviewer", etc.)
Is the agent scoped to a specific domain? ("focuses on the rendering pipeline", "works across the full monorepo", etc.)
Any role constraints? ("never makes architectural decisions alone")

Turn 2 — Communication Style

How verbose should responses be? (concise summaries, detailed explanations, adaptive to the question?)
Preferred format for code changes? (show diffs, show full files, inline comments, separate explanation block?)
How should the agent handle uncertainty? ("state assumption and proceed", "always ask before proceeding", "ask for scope-changing uncertainty only"?)
Should the agent explain its reasoning, or just act?

Turn 3 — Workflow Procedures

What is the standard flow for a new feature? (e.g., propose → spec → design → implement → test → PR)
For bug fixes, is the flow different?
What checks must always run before committing? (type-check, lint, tests?)
Any PR conventions? (size limits, labels, draft vs. ready, review requests?)
Commit message convention? (Conventional Commits, gitmoji, free-form, with example format?)
Versioning workflow? (when to bump, who approves changelog?)

Turn 4 — OpenSpec / Spec-Driven Workflow (skip if not using OpenSpec)

When should the agent invoke
```
/opsx:propose
```
? Good default: "for any new feature or non-trivial change".
When is a spec required vs. optional?
Should the agent reference existing specs before creating new patterns?
How should the agent handle a task that has no existing spec?

Turn 5 — Decision Heuristics

When should the agent ask vs. proceed autonomously? Good prompts: "deleting files", "changing public APIs", "modifying migrations", "adding new dependencies".
Any operations that require explicit human sign-off before acting?
How should scope creep be handled if discovered mid-task?
If two approaches are equally valid, should the agent pick one, ask, or present both?

Turn 6 — Tool & Command Preferences

Any tool-level preferences the agent should honor? Examples: "prefer vitest over jest", "use pnpm, never npm", "biome for formatting, never prettier".
Any CLI commands the agent should always/never run? Examples: "never run
git push --force
", "always use
pnpm
not
npm run
".
Any environment setup the agent should validate before starting?

Turn 7 — Guardrails

Hard "never" rules? (operations that are always off-limits) Examples: "never force-push to main", "never delete migration files", "never commit secrets".
Soft "always ask first" rules? Examples: "ask before modifying
package.json
scripts", "ask before changing shared utility packages".
Any security-sensitive areas that require special handling?

以对话形式开展访谈，不要一次性抛出所有问题，按主题自然分组提问。如果用户描述了工作流程，可以推断相关的行为约束并向用户确认，无需重复提问。

第一轮 — 角色与身份

Agent应该承担什么角色？（"高级TypeScript工程师"、"全栈开发者"、"结对程序员"、"代码评审员"等）
Agent是否有特定的领域范围？（"专注于渲染管线"、"负责整个monorepo的工作"等）
有没有角色限制？（"不得独自做出架构决策"）

第二轮 — 沟通风格

响应的详细程度应该如何？（简洁总结、详细解释、根据问题自适应？）
代码变更的首选展示格式？（展示差异、展示完整文件、行内注释、单独的说明块？）
Agent应该如何处理不确定性？（"说明假设后继续"、"操作前必须询问"、"仅涉及范围变更的不确定性需要询问"？）
Agent应该解释推理过程，还是直接执行操作？

第三轮 — 工作流程规范

新功能的标准流程是什么？（例如：提案→ spec →设计→实现→测试→PR）
Bug修复的流程是否不同？
提交前必须运行哪些检查？（类型检查、lint、测试？）
有没有PR规范？（大小限制、标签、草稿vs就绪、评审请求规则？）
提交信息规范？（Conventional Commits、gitmoji、自由格式、可提供示例格式？）
版本管理流程？（什么时候升级版本、谁负责审批变更日志？）

第四轮 — OpenSpec/ spec驱动工作流 (如果未使用OpenSpec可跳过)

Agent什么时候应该调用
```
/opsx:propose
```
？ 推荐默认值："任何新功能或非 trivial 变更"。
什么时候必须提供spec，什么时候可选？
Agent在创建新模式前是否应该参考现有spec？
Agent应该如何处理没有对应现有spec的任务？

第五轮 — 决策规则

Agent什么时候应该询问，什么时候可以自主执行？ 参考提示："删除文件"、"修改公共API"、"修改迁移文件"、"新增依赖"。
有没有操作需要明确的人工审批才能执行？
任务执行中发现范围蔓延应该如何处理？
如果两种方案效果相当时，Agent应该自行选择一种、询问用户、还是同时展示两种方案？

第六轮 — 工具与命令偏好

Agent应该遵守哪些工具层面的偏好？ 示例："优先使用vitest而非jest"、"使用pnpm，不要用npm"、"用biome格式化，不要用prettier"。
Agent应该始终/永远不要运行哪些CLI命令？示例："永远不要运行
git push --force
"、"始终使用
pnpm
而非
npm run
"。
开始工作前Agent应该验证哪些环境配置？

第七轮 — 护栏

硬性禁止规则？（永远不允许执行的操作） 示例："永远不要强制推送main分支"、"永远不要删除迁移文件"、"永远不要提交密钥"。
软性前置询问规则？示例："修改
package.json
脚本前先询问"、"修改共享工具包前先询问"。
有没有需要特殊处理的安全敏感区域？

Phase 2 — Smart Defaults

阶段2 — 智能默认值确认

After each workflow answer, surface relevant behavioral conventions to confirm. Use these examples as a pattern; extend to other stacks as appropriate.

Turborepo + PNPM monorepo → suggest confirming:

"I'll assume you want
```
pnpm -w
```
(workspace root) for adding shared deps and
```
pnpm --filter <pkg>
```
for package-scoped deps; correct?"
"For tasks, I'll default to
```
pnpm turbo run build --filter=...
```
rather than running package scripts directly; correct?"

GitHub Actions CI → suggest confirming:

"Should I wait for CI to pass before treating a PR as mergeable?"
"Any required status checks the agent should reference before marking work done?"

Conventional Commits → suggest confirming:

"I'll use
```
feat:
```
,
```
fix:
```
,
```
chore:
```
,
```
docs:
```
,
```
test:
```
,
```
refactor:
```
— any additional types your team uses (e.g.,
```
perf:
```
,
```
ci:
```
)?"
"Are breaking changes annotated with
```
!
```
suffix (e.g.,
```
feat!:
```
) or with a footer
```
BREAKING CHANGE:
```
block?"

Spec-Driven Development (OpenSpec) → suggest confirming:

"For non-trivial changes, I'll start with
```
/opsx:propose
```
before writing any code; should I also require a design artifact for changes touching more than N files?"
"Should I link task IDs or spec refs in commit messages?"

每个工作流程问题得到答复后，给出相关的行为惯例建议供用户确认。以下示例作为参考，可适配其他技术栈扩展。

Turborepo + PNPM monorepo → 建议确认：

"我默认你希望添加共享依赖时使用
```
pnpm -w
```
（工作区根目录），包级别的依赖使用
```
pnpm --filter <pkg>
```
，是否正确？"
"执行任务时我会默认使用
```
pnpm turbo run build --filter=...
```
而非直接运行包脚本，是否正确？"

GitHub Actions CI → 建议确认：

"我是否应该等待CI通过后再认为PR可合并？"
"有没有Agent在标记工作完成前需要参考的强制状态检查？"

Conventional Commits → 建议确认：

"我会使用
```
feat:
```
、
```
fix:
```
、
```
chore:
```
、
```
docs:
```
、
```
test:
```
、
```
refactor:
```
这些类型，你的团队有没有使用其他额外类型（例如
```
perf:
```
、
```
ci:
```
）？"
"破坏性变更用
```
!
```
后缀标记（例如
```
feat!:
```
）还是用页脚
```
BREAKING CHANGE:
```
块标记？"

Spec驱动开发（OpenSpec）→ 建议确认：

"对于非 trivial 变更，我会在写代码前先执行
```
/opsx:propose
```
，对于修改超过N个文件的变更，我是否还需要设计产物？"
"我是否应该在提交信息中关联任务ID或spec引用？"

Phase 3 — Codebase Inference (fill gaps before generating)

阶段3 — 代码库推断（生成前补全空缺）

After the interview, audit every AGENTS.md section that still has no answer. For each gap, attempt to derive the behavioral intent directly from the codebase before asking or leaving a

# TODO

. A behavioral file with explicit TODOs is actionable; a file with missing sections silently shapes agent behavior in unpredictable ways.

Inference targets and where to look:

Gap	Files / signals to inspect
Commit convention	`commitlint.config.` , recent `git log --oneline` , `.gitmessage` , `.releaserc`
PR workflow	`.github/PULL_REQUEST_TEMPLATE.md` , `.github/workflows/` (CI gate names)
Pre-commit checks	`.husky/` , `.lefthook.yml` , `package.json#scripts` (lint, typecheck, test)
Test runner preference	`vitest.config.` , `jest.config.` — whichever is present
Package manager	`package-lock.json` , `yarn.lock` , `pnpm-lock.yaml` , `bun.lockb`
Forced-push protection	`.github/branch-protection*` , README mentions of branch policy
Migration guardrails	Presence of `migrations/` , `prisma/migrations/` , `alembic/`
Secret handling	`.env.example` , `.gitignore` patterns, presence of `dotenv` / vault tooling
OpenSpec usage	`openspec/` directory, `openspec/config.yaml` , any `/opsx:*` references in docs
Versioning workflow	`.changeset/` , `CHANGELOG.md` , `standard-version` , `conventional-changelog`
Path aliases (for tool commands)	`tsconfig.json#paths` , `vite.config` — infer preferred import style

After inference, for each field resolved this way, note the source in the preview with a trailing comment, e.g.:

markdown

- Always run `pnpm check` before committing   # inferred from .husky/pre-commit
- Use Conventional Commits (`feat:`, `fix:`)  # inferred from commitlint.config.ts

If a field genuinely cannot be inferred (e.g., decision heuristics, communication style, role definition), mark it with

<!-- TODO: fill in -->

rather than omitting the section.

访谈结束后，检查所有仍然没有答案的AGENTS.md章节。对于每个空缺，先尝试直接从代码库推断行为意图，再考虑提问或留下

# TODO

标记。带有明确TODO的行为文件是可执行的，而 silently 缺失章节的文件会以不可预测的方式影响Agent行为。

推断目标与检测位置：

空缺内容	检测文件/信号
提交规范	`commitlint.config.` 、最近的 `git log --oneline` 、 `.gitmessage` 、 `.releaserc`
PR工作流	`.github/PULL_REQUEST_TEMPLATE.md` 、 `.github/workflows/` （CI卡点名称）
预提交检查	`.husky/` 、 `.lefthook.yml` 、 `package.json#scripts` （lint、typecheck、test）
测试运行器偏好	`vitest.config.` 、 `jest.config.` — 存在的配置对应工具
包管理器	`package-lock.json` 、 `yarn.lock` 、 `pnpm-lock.yaml` 、 `bun.lockb`
强制推送保护	`.github/branch-protection*` 、README中提及的分支策略
迁移护栏	是否存在 `migrations/` 、 `prisma/migrations/` 、 `alembic/`
密钥处理	`.env.example` 、 `.gitignore` 规则、是否存在 `dotenv` /密钥管理工具
OpenSpec使用情况	`openspec/` 目录、 `openspec/config.yaml` 、文档中是否有 `/opsx:*` 引用
版本管理流程	`.changeset/` 、 `CHANGELOG.md` 、 `standard-version` 、 `conventional-changelog`
路径别名（工具命令用）	`tsconfig.json#paths` 、 `vite.config` — 推断优先导入风格

推断完成后，每个通过此方式填充的字段，在预览中添加末尾注释说明来源，例如：

markdown

- 提交前始终运行`pnpm check`   # 从.husky/pre-commit推断
- 使用Conventional Commits规范（`feat:`、`fix:`）  # 从commitlint.config.ts推断

如果某个字段确实无法推断（例如决策规则、沟通风格、角色定义），用

<!-- TODO: fill in -->

标记，不要省略该章节。

Phase 4 — Preview and Write

阶段4 — 预览与写入

Show a labeled preview of the full AGENTS.md before writing anything. Inferred values carry their source comment; unresolved sections carry
```

```
. This gives the user a complete confidence map.
Ask: "Does this look right? Any sections to correct or expand before I write the file?"
After confirmation, write to
```
AGENTS.md
```
at the project root (or
```
CLAUDE.md
```
if the user is using Claude Code conventions), stripping the inference source comments — they are for review only, not the final file.
Print a brief summary of what was generated, what was inferred vs. answered directly, and which
```

```
sections still need human input.

写入前先展示带标记的完整AGENTS.md预览，推断值带有来源注释，未解决章节带有
```

```
，让用户完全了解内容情况。
询问："内容是否正确？写入文件前有没有需要修改或补充的章节？"
确认后，写入项目根目录的
```
AGENTS.md
```
（如果用户使用Claude Code规范则写入
```
CLAUDE.md
```
），移除推断来源注释——这些注释仅用于评审，不出现在最终文件中。
输出简短摘要，说明生成的内容、哪些是推断的、哪些是用户直接回答的，以及哪些
```

```
章节仍然需要人工补充。

AGENTS.md Template

AGENTS.md模板

Use this exact structure. Fill every

[placeholder]

with content from the interview or codebase inference. If a field cannot be resolved by either means, replace its placeholder with

<!-- TODO: fill in -->

— never omit the section. Every section shapes global agent behavior.

markdown

undefined

使用以下固定结构，将所有

[占位符]

替换为访谈或代码库推断的内容。如果某个字段两种方式都无法填充，将占位符替换为

<!-- TODO: fill in -->

——永远不要省略章节，每个章节都会影响Agent的全局行为。

markdown

undefined

Agent Behavior

Agent行为规范

NOTE: This file governs HOW the agent behaves. Project facts (stack, architecture, domain concepts, coding standards) belong in
openspec/config.yaml
, not here. See the separation of concerns in the OpenSpec documentation.

注意：本文件规范Agent的行为方式。项目相关事实（技术栈、架构、领域概念、编码标准）属于
openspec/config.yaml
的内容，不应放在此处。可参考OpenSpec文档中的关注点分离说明。

Role & Identity

角色与身份

[One-sentence role definition, e.g., "You are a senior TypeScript engineer working across the @accelint/* monorepo."]

[Scope constraints, if any, e.g., "Focus on rendering pipeline packages (@accelint/standard-toolkit, @accelint/layer-orchestration). Escalate cross-cutting architectural decisions."]

[一句话角色定义，例如："你是负责@accelint/* 全monorepo开发的高级TypeScript工程师。"]

[范围限制（如有），例如："专注于渲染管线包（@accelint/standard-toolkit、@accelint/layer-orchestration），跨领域架构决策需要升级处理。"]

Communication

沟通规则

Response style: [concise / detailed / adaptive — describe when each applies]
Code changes: [show diffs / show full file / inline comments / separate block]
Uncertainty: [always ask / ask for scope-changing uncertainty only / state assumption and proceed]
Reasoning: [explain reasoning / act without narrating / explain only when asked]

响应风格: [简洁/详细/自适应 — 说明适用场景]
代码变更展示: [展示差异/展示完整文件/行内注释/单独说明块]
不确定性处理: [始终询问/仅范围变更时询问/说明假设后继续]
推理说明: [解释推理过程/直接执行不说明/仅被询问时解释]

Workflow Procedures

工作流程规范

New Features

新功能开发

[step-by-step procedure, e.g.:]

Start with
```
/opsx:propose
```
for any non-trivial change
Get proposal reviewed before writing code
Run
```
pnpm check
```
and
```
pnpm test
```
after each meaningful change
Open a draft PR early; mark ready only after CI passes

[分步流程，例如：]

任何非 trivial 变更先执行
```
/opsx:propose
```
写代码前先获得提案评审通过
每次有意义的变更后运行
```
pnpm check
```
和
```
pnpm test
```
尽早提交草稿PR，CI通过后再标记为就绪

Bug Fixes

Bug修复

[procedure — often shorter than feature flow, e.g.:]

Reproduce with a failing test before touching code
Fix the root cause, not the symptom
Confirm the test passes, then open a PR

[流程——通常比功能流程短，例如：]

改代码前先编写失败的测试复现问题
修复根本原因而非表面症状
确认测试通过后提交PR

Pre-Commit Checklist

预提交检查清单

[check, e.g.,
```
pnpm typecheck
```
]
[check, e.g.,
```
pnpm lint
```
]
[check, e.g.,
```
pnpm test
```
]

[检查项，例如：
```
pnpm typecheck
```
]
[检查项，例如：
```
pnpm lint
```
]
[检查项，例如：
```
pnpm test
```
]

Commit Messages

提交信息

Convention: [e.g., Conventional Commits] Format:

[type]([scope]): [description]

Types:

feat

fix

chore

docs

test

refactor

[, additional types] Example:

feat(layer): add WebGPU fallback for Safari

规范: [例如：Conventional Commits] 格式:

[type]([scope]): [description]

类型:

feat

、

fix

、

chore

、

docs

、

test

、

refactor

[, 额外类型] 示例:

feat(layer): 为Safari添加WebGPU降级方案

PR Conventions

PR规范

[size guideline, e.g., "prefer small, focused PRs over large changesets"]
[label convention, if any]
[review request convention, if any]

[大小指引，例如："优先提交小而聚焦的PR，避免大型变更集"]
[标签规范（如有）]
[评审请求规范（如有）]

Versioning

版本管理

[when and how to bump versions, e.g., "use
```
pnpm changeset
```
for any user-facing change; patch for fixes, minor for features, major for breaking changes"]

[升级版本的时机和方式，例如："任何面向用户的变更使用
```
pnpm changeset
```
；修复升级补丁版本、新功能升级次版本、破坏性变更升级主版本"]

Decision Heuristics

决策规则

Situation	Default Action
Uncertain about scope	[ask / proceed with stated assumption]
Deleting files	[always ask first]
Changing public API	[always ask first]
Adding a new dependency	[ask, state rationale]
Modifying shared utilities	[ask, list affected packages]
Discovering scope creep mid-task	[pause and surface to user]
Two equally valid approaches	[pick one and state choice / ask]
[additional heuristics]

场景	默认行为
范围不明确	[询问/说明假设后继续]
删除文件	[始终先询问]
修改公共API	[始终先询问]
新增依赖	[询问并说明理由]
修改共享工具	[询问并列出受影响的包]
任务执行中发现范围蔓延	[暂停并告知用户]
两种方案效果相当	[选择一种并说明/询问用户]
[额外规则]

Tool Preferences

工具偏好

Package manager: [e.g., always use
```
pnpm
```
; never
```
npm
```
or
```
yarn
```
]
Test runner: [e.g.,
```
vitest
```
— never
```
jest
```
]
Linting / formatting: [e.g.,
```
biome
```
— never
```
prettier
```
or
```
eslint
```
separately]
Task runner: [e.g.,
```
pnpm turbo run <task> --filter=<pkg>
```
]
Version control: [e.g.,
```
git
```
via CLI — no GUI wrappers] [additional tool preferences]

包管理器: [例如：始终使用
```
pnpm
```
，不要用
```
npm
```
或
```
yarn
```
]
测试运行器: [例如：
```
vitest
```
，不要用
```
jest
```
]
Lint/格式化: [例如：
```
biome
```
，不要单独使用
```
prettier
```
或
```
eslint
```
]
任务运行器: [例如：
```
pnpm turbo run <task> --filter=<pkg>
```
]
版本控制: [例如：通过CLI使用
```
git
```
，不要用GUI封装工具] [额外工具偏好]

Guardrails

护栏

Never (hard stops — no exceptions)

绝对禁止（无例外的硬性规则）

Never force-push to
```
main
```
or
```
[protected branch]
```
Never commit secrets, tokens, or credentials
[additional hard stop]

永远不要强制推送
```
main
```
或
```
[保护分支]
```
永远不要提交密钥、token或凭证
[额外硬性禁止规则]

Always Ask First (soft gates)

必须先询问（软性卡点）

Before deleting any tracked file
Before modifying
```
package.json
```
scripts in a shared package
Before changing a migration file
[additional soft gate]

删除任何被跟踪的文件前
修改共享包的
```
package.json
```
脚本前
修改迁移文件前
[额外软性询问规则]

Security Sensitivity

安全敏感区域

[any areas requiring special care, e.g., "treat all environment variable names as sensitive — never log them, even in debug output"]

---

[任何需要特殊注意的区域，例如："所有环境变量名称视为敏感信息，即使在调试输出中也不要记录"]

---

Interaction Principles

交互原则

Conversational, not interrogative. Bundle related questions into a single turn. Use natural language, not bullet-dump forms.
Infer and confirm. "You mentioned Husky — I'll assume the pre-commit hook runs
```
pnpm check
```
; can you confirm?" is better than asking from scratch.
Examples reduce ambiguity. When asking about decision heuristics, offer concrete triggering scenarios so the user can pattern-match.
Iterative. Let the user amend answers before the final write.
Preview before writing. Always show the full generated AGENTS.md and get explicit confirmation before touching the filesystem.
Infer before asking, ask before omitting. A file with explicit TODOs is actionable; a file with missing sections silently degrades every interaction it governs.
Don't cross the layer boundary. If the user volunteers stack facts during this interview, acknowledge them and note they belong in
```
openspec/config.yaml
```
, not AGENTS.md. Offer to run the
```
accelint-onboard-openspec
```
skill for that content.

对话式而非审问式，将相关问题合并到同一轮提问，使用自然语言，不要批量抛出问题列表。
先推断再确认，"你提到了Husky，我默认预提交钩子会运行
```
pnpm check
```
，可以确认吗？"比从零开始提问效果更好。
示例减少歧义，询问决策规则时提供具体的触发场景，方便用户匹配规则。
迭代式，最终写入前允许用户修改答案。
写入前预览，始终展示完整的生成AGENTS.md内容，获得明确确认后再修改文件系统。
先推断再提问，先提问再省略，带有明确TODO的文件是可执行的，缺失章节的文件会悄悄降低所有交互的质量。
不要跨层，如果用户在访谈中主动提到技术栈相关事实，告知这些内容属于
```
openspec/config.yaml
```
而非AGENTS.md，可提供运行
```
accelint-onboard-openspec
```
技能处理这些内容的选项。