ethos

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Ethos Generator

项目Ethos生成工具

Generate and maintain an

ethos/

folder that gives agents and humans the strategic context behind a project. Three documents, all interview-generated:

vision.md — Why this exists, who it's for, what success looks like
principles.md — Technical and product tradeoffs, guardrails, beliefs
non-goals.md — What the project intentionally avoids

生成并维护一个

ethos/

文件夹，为Agent和人类提供项目背后的战略背景。包含三个通过访谈生成的文档：

vision.md — 项目存在的原因、服务对象、成功的定义
principles.md — 技术与产品的权衡准则、约束条件、核心理念
non-goals.md — 项目明确要避免的内容

Modes

模式

Detect the correct mode from context. If the user says "ethos" without specifying, check whether

ethos/

exists in the project root:

If no: run
```
/ethos:init
```
If yes: run
```
/ethos:audit
```

根据上下文自动检测正确模式。如果用户只提到“ethos”未指定具体操作，检查项目根目录是否存在

ethos/

文件夹：

不存在：执行
```
/ethos:init
```
已存在：执行
```
/ethos:audit
```

Mode 1:

/ethos:init

— Generate Ethos

模式1：

/ethos:init

— 生成Ethos

Trigger: No

ethos/

folder exists, or user explicitly asks to create one. What it does: Adaptive interview → generates all 3 files → adds CLAUDE.md pointer. Read before running:

references/output-formats.md

触发条件： 不存在

ethos/

文件夹，或用户明确要求创建。 功能： 自适应访谈 → 生成全部3份文档 → 添加CLAUDE.md指向链接。 执行前必读：

references/output-formats.md

Mode 2:

/ethos:audit

— Audit Existing Ethos

模式2：

/ethos:audit

— 审计现有Ethos

Trigger:

ethos/

folder exists and user wants to check if it's still accurate. What it does: Reads ethos docs, scans codebase, reports completeness and relevance.

触发条件： 已存在

ethos/

文件夹，且用户希望检查其准确性。 功能： 读取Ethos文档、扫描代码库，报告文档的完整性和相关性。

Mode 3:

/ethos:refresh

— Update a Specific Document

模式3：

/ethos:refresh

— 更新指定文档

Trigger: User wants to update a specific ethos doc (e.g.,

/ethos:refresh vision

). What it does: Reads the existing doc → targeted re-interview → surgical update. Read before running:

references/output-formats.md

触发条件： 用户希望更新某份特定的Ethos文档（例如

/ethos:refresh vision

）。 功能： 读取现有文档 → 针对性重访谈 → 精准更新。 执行前必读：

references/output-formats.md

Mode 1: Init — Full Protocol

模式1：初始化 — 完整流程

This skill is fundamentally an interview tool. Unlike clarification questions in other skills, the interview here IS the product — it surfaces beliefs the user hasn't articulated yet. The adaptive flow asks core questions first, then follows up where answers reveal something interesting.

本工具本质是一个访谈工具。与其他工具中的澄清问题不同，这里的访谈本身就是核心产出——它能挖掘出用户尚未明确表达的理念。自适应流程会先提出核心问题，再根据回答中的有趣点进行跟进。

Step 1: Check for Existing Ethos

步骤1：检查现有Ethos

Use Glob to check if

ethos/

already exists in the project root.

If it exists: warn the user and ask if they want to overwrite or run audit instead.
If not: proceed.

使用Glob检查项目根目录是否已存在

ethos/

。

已存在：提醒用户，并询问是否要覆盖或改为执行审计。
不存在：继续执行。

Step 2: Read Output Templates

步骤2：读取输出模板

Read

references/output-formats.md

to understand the target format for all 3 documents.

读取

references/output-formats.md

，了解三份文档的目标格式。

Step 2.5: Codebase Reconnaissance

步骤2.5：代码库侦察

Before starting the interview, silently scan the project to inform your questions. Read/check (don't narrate this to the user):

```
README.md
```
— project description, stated audience, tech stack
```
CLAUDE.md
```
/
```
AGENTS.md
```
— existing conventions or philosophy
```
package.json
```
,
```
pyproject.toml
```
,
```
Cargo.toml
```
, or equivalent — dependencies, scripts
Top-level directory structure via Glob (
```
*
```
) — what modules/areas exist

Use these findings to:

Generate persona options grounded in the actual project (not generic archetypes)
Pre-fill non-goal options based on what the project clearly isn't
Ask about things you noticed rather than generic tradeoffs
Skip questions the codebase already answers (e.g., don't ask "who is this for?" if the README has a clear audience statement — instead confirm and ask follow-ups)

开始访谈前，静默扫描项目以优化问题设计。读取/检查以下内容（无需告知用户）：

```
README.md
```
— 项目描述、声明的受众、技术栈
```
CLAUDE.md
```
/
```
AGENTS.md
```
— 现有约定或理念
```
package.json
```
、
```
pyproject.toml
```
、
```
Cargo.toml
```
或等效文件 — 依赖项、脚本
通过Glob(
```
*
```
)查看顶层目录结构 — 存在哪些模块/领域

利用这些发现：

基于实际项目生成用户角色选项（而非通用模板）
根据项目明显不涉及的内容预先提供非目标选项
针对观察到的问题提问，而非通用权衡问题
跳过代码库已能回答的问题（例如，如果README已明确受众，就不要问“服务对象是谁？”，而是确认并跟进相关问题）

Step 3: Interview — Vision

步骤3：访谈 — 愿景

Ask 2-4 questions using AskUserQuestion. Core questions:

Why does this project exist? What problem does it solve, and why is that problem worth solving? (Free text via "Other" — don't constrain with options here)
Who is the primary user? Offer 3-4 persona archetypes based on what you can infer from the codebase (package.json, README, etc.), plus "Other."
What does success look like? Not metrics — what observable outcome would mean this project achieved its purpose?

Based on answers, ask 1-2 follow-up questions if something is ambiguous or interesting. Then ask: "Is there another distinct user group?" Repeat until the user says no.

使用AskUserQuestion提出2-4个核心问题：

项目存在的原因是什么？ 解决了什么问题，为什么这个问题值得解决？（通过“其他”选项支持自由文本输入——不要用选项限制用户）
主要用户是谁？ 根据从代码库（package.json、README等）推断的结果，提供3-4个用户角色原型，外加“其他”选项。
成功的定义是什么？ 不是指标，而是可观察到的、表明项目已达成目标的结果。

根据回答，若存在模糊或有趣的点，提出1-2个跟进问题。然后询问：“是否存在其他不同的用户群体？” 直到用户回答“否”为止。

Step 4: Interview — Principles

步骤4：访谈 — 原则

Ask 2-3 questions using AskUserQuestion:

What tradeoff would a new contributor get wrong? e.g., "They'd over-engineer the auth system" or "They'd optimize for performance when we care about DX." Offer 3-4 common tradeoff pairs as options.
When you disagree with a PR, what's usually the reason? This surfaces unstated beliefs about code quality, architecture, or product direction.
What's a technical decision you've made that surprised people? This often reveals the most distinctive principles.

Based on answers, ask 1-2 follow-ups if a principle needs clarification.

When two principles conflict, which one wins? e.g., "Security makes something harder to use — do you choose security or simplicity?" This produces a priority stack that agents can use as a tiebreaker for real decisions.

使用AskUserQuestion提出2-3个问题：

新贡献者最容易搞错的权衡是什么？ 例如“他们会过度设计认证系统”或“当我们关注开发者体验时，他们却在优化性能”。提供3-4个常见权衡对作为选项。
你拒绝PR的常见原因是什么？ 这能揭示未明确表达的关于代码质量、架构或产品方向的理念。
你做出过哪些让人意外的技术决策？ 这通常能反映出最具特色的原则。

根据回答，若某条原则需要澄清，提出1-2个跟进问题。

当两条原则冲突时，哪一条优先级更高？ 例如“安全性会降低易用性——你会选择安全性还是简洁性？” 这会生成一个优先级排序，Agent可将其作为实际决策中的 tiebreaker（平局决胜规则）。

Step 5: Interview — Non-Goals

步骤5：访谈 — 非目标

Ask 1-2 questions using AskUserQuestion:

What has this project intentionally said no to? Offer 3-4 options based on common non-goals for the project type (e.g., "Enterprise features," "Multi-tenancy," "Backwards compatibility with v1"), plus "Other."
What should an agent working on this project never optimize for? This catches non-goals that aren't obvious from the codebase.

使用AskUserQuestion提出1-2个问题：

项目明确拒绝过哪些内容？ 根据项目类型提供3-4个常见非目标选项（例如“企业级功能”、“多租户”、“与v1版本向后兼容”），外加“其他”选项。
参与该项目的Agent绝对不应该优化的是什么？ 这能捕捉到代码库中不明显的非目标。

Interview Guidance: Multi-Select and "All of the Above"

访谈指导：多选与“全部适用”

Many interview questions benefit from multi-select. When offering options, explicitly tell the user they can pick more than one: "Pick all that apply (or add your own via Other)." After they select multiple options, follow up to rank them: "You picked A, B, and C — if you had to order them by importance, what's the ranking?"

If the user selects ALL options or says "all of the above," follow up with a forcing question: "If you had to pick the ONE that matters most, which would it be?" The goal is to surface priority, not just agreement. Every option being equally important means none of them are — push for differentiation.

许多访谈问题适合使用多选模式。提供选项时，明确告知用户可多选：“选择所有适用的选项（或通过‘其他’添加自定义内容）”。用户选择多个选项后，跟进询问优先级：“你选择了A、B和C——如果必须按重要性排序，顺序是什么？”

如果用户选择了所有选项或说“全部适用”，则提出强制选择问题：“如果必须选一个最重要的，你会选哪一个？” 目标是挖掘优先级，而非仅仅达成共识。所有选项同等重要意味着没有一个是核心——要推动用户做出区分。

Step 5.5: Synthesis Playback

步骤5.5：总结回放

Before generating files, present a brief synthesis of what you heard:

"Here's what I took away from our conversation — [3-5 bullet points covering the key vision, principles, and non-goals]. Anything I'm missing or getting wrong?"

Use AskUserQuestion with options like "Looks good, generate the files" / "Let me clarify something." This catches misinterpretations before they're baked into prose — especially important when the user gave rich free-text answers.

生成文件前，先向用户简要总结访谈内容：

“以下是我从对话中总结的核心内容——[3-5个要点，涵盖关键愿景、原则和非目标]。有没有遗漏或理解错误的地方？”

使用AskUserQuestion提供选项，例如“没问题，生成文件” / “我需要澄清一些内容”。这能在内容被写入文档前纠正误解——尤其是当用户提供了丰富的自由文本回答时。

Step 6: Generate Files

步骤6：生成文件

Using the interview answers and the templates from

references/output-formats.md

, generate all three files:

Write
```
ethos/vision.md
```
Write
```
ethos/principles.md
```
Write
```
ethos/non-goals.md
```

Generation rules:

Use the user's own words where possible — don't sanitize their voice into corporate speak
Every principle must have a concrete This means section
Every non-goal must have a What to do instead redirect
Personas must be specific enough to change agent behavior
Keep each file focused — vision.md should be under 80 lines, principles.md under 120, non-goals.md under 60
Deduplication pass: After drafting all three files, check for concepts that appear in both principles.md and non-goals.md. If something is a scoping principle (what we focus on), keep it in principles. If it's a boundary (what we refuse to do), keep it in non-goals. Never both.

利用访谈答案和

references/output-formats.md

中的模板，生成全部三份文件：

编写
```
ethos/vision.md
```
编写
```
ethos/principles.md
```
编写
```
ethos/non-goals.md
```

生成规则：

尽可能使用用户的原话——不要将其表述 sanitize（净化）为企业话术
每条原则必须包含具体的这意味着部分
每个非目标必须包含替代方案指引
用户角色必须足够具体，能够影响Agent的行为
每份文件需聚焦核心内容——vision.md不超过80行，principles.md不超过120行，non-goals.md不超过60行
去重检查： 完成所有文件草稿后，检查principles.md和non-goals.md中重复的概念。如果是范围性原则（我们关注的内容），保留在principles中；如果是边界性规则（我们拒绝的内容），保留在non-goals中。不可同时出现在两份文件中。

Step 6.5: Decision Tests

步骤6.5：决策测试

Generate 2-3 "decision tests" — hypothetical scenarios the ethos should resolve — and present them to the user:

"To make sure this captures what you meant, here are a few test decisions:"

Q: Should we add a GraphQL layer? → A: Principle "Simplicity over flexibility" says no — stick with REST unless a specific consumer needs it.

Q: Should we support IE11? → A: Non-goal "Legacy browser support" says no — redirect to the progressive enhancement approach.

Ask: "Do these answers match your intuition?" If any feel wrong, revisit the relevant principle or non-goal before finalizing. These tests also get appended to principles.md as a "Decision Tests" section (see output-formats.md template).

生成2-3个“决策测试”——即Ethos应能解决的假设场景，并呈现给用户：

“为确保内容符合你的预期，以下是几个测试场景：”

问题：我们应该添加GraphQL层吗？ → 答案：原则「简洁优先于灵活」要求不添加——除非特定用户有需求，否则坚持使用REST。

问题：我们应该支持IE11吗？ → 答案：非目标「遗留浏览器支持」要求不支持——采用渐进增强方案。

询问：“这些答案符合你的预期吗？” 如果有任何不符合的，在最终确定前重新审视相关原则或非目标。这些测试也会作为“决策测试”部分添加到principles.md中（参考output-formats.md模板）。

Step 7: Add CLAUDE.md Pointer

步骤7：添加CLAUDE.md指向链接

Check if CLAUDE.md (or AGENTS.md) exists in the project root:

If it exists: Check if an ethos section is already present. If not, append:

markdown

undefined

检查项目根目录是否存在CLAUDE.md（或AGENTS.md）：

已存在： 检查是否已包含Ethos部分。如果没有，追加：

markdown

undefined

Project Ethos

项目Ethos

Read the

ethos/

directory for the project's vision, principles, personas, and non-goals. Consult these before making architectural or UX decisions.


- **If it doesn't exist:** Skip. Don't create CLAUDE.md — that's the user's decision.
  Instead, tell the user: "Consider adding a pointer to ethos/ in your CLAUDE.md."

请查看

ethos/

目录获取项目的愿景、原则、用户角色和非目标。在做出架构或UX决策前，请先参考这些内容。


- **不存在：** 跳过。不要创建CLAUDE.md——这是用户的决策。而是告知用户：“建议在你的CLAUDE.md中添加指向ethos/的链接。”

Step 8: Summary

步骤8：总结

Present what was generated:

List the 3 files with a 1-line summary of each
Note the CLAUDE.md status (updated / already had pointer / no CLAUDE.md found)
Offer: "Want me to adjust anything?"

向用户展示生成的内容：

列出3份文件，并分别用1句话总结
说明CLAUDE.md的状态（已更新 / 已存在指向链接 / 未找到CLAUDE.md）
询问：“需要我调整任何内容吗？”

Mode 2: Audit — Full Protocol

模式2：审计 — 完整流程

Step 1: Read Existing Ethos

步骤1：读取现有Ethos

Read all files in

ethos/

. If any of the 3 expected files are missing, flag them.

读取

ethos/

中的所有文件。如果缺少3份预期文件中的任何一份，标记出来。

Step 2: Check Completeness

步骤2：检查完整性

For each file, verify:

vision.md: Has a Why section, at least one persona, and success criteria
principles.md: Has at least 3 principles, each with Why and This means sections
non-goals.md: Has at least 2 non-goals, each with Why not and What to do instead

Flag any missing or empty sections.

对每份文件，验证：

vision.md： 包含“原因”部分、至少一个用户角色、成功标准
principles.md： 包含至少3条原则，每条原则包含“原因”和“这意味着”部分
non-goals.md： 包含至少2个非目标，每个非目标包含“为什么不”和“替代方案”部分

标记任何缺失或空白的部分。

Step 3: Check Relevance

步骤3：检查相关性

Scan the codebase for signals that the ethos may have drifted:

Tech stack changes: Use Glob/Grep to check if technologies mentioned in principles still appear in the codebase (e.g., a principle about PostgreSQL when the project moved to SQLite)
Structural shifts: Check if the project's scope has visibly expanded or narrowed since the ethos was written (new top-level directories, major dependency changes)
Persona validity: Check if the README or docs still describe the same target users

Don't flag style or wording issues — only substantive drift.

扫描代码库，寻找Ethos可能已偏离的信号：

技术栈变化： 使用Glob/Grep检查原则中提到的技术是否仍在代码库中使用（例如，原则中提到PostgreSQL，但项目已迁移到SQLite）
结构变化： 检查自Ethos编写以来，项目范围是否明显扩大或缩小（新增顶层目录、重大依赖项变化）
用户角色有效性： 检查README或文档是否仍描述相同的目标用户

不要标记风格或措辞问题——仅标记实质性偏离。

Step 4: Report

步骤4：生成报告

Output a structured report:

undefined

输出结构化报告：

undefined

Ethos Audit

Ethos审计报告

Completeness

完整性

vision.md — all sections present
principles.md — missing "This means" on principle 3
non-goals.md — all sections present

vision.md — 所有部分齐全
principles.md — 第3条原则缺少“这意味着”部分
non-goals.md — 所有部分齐全

Relevance Flags

Recommendations

建议

[action]: Update principles.md to reflect Fastify migration
[action]: Consider adding an API consumer persona to vision.md


If everything checks out, say so briefly and don't invent issues.

---


如果一切正常，简要说明即可，不要编造问题。

---

Mode 3: Refresh — Full Protocol

模式3：更新 — 完整流程

Step 1: Parse Target

步骤1：解析目标

The user specifies which doc to refresh:

vision

principles

, or

non-goals

. If not specified, ask which one.

用户指定要更新的文档：

vision

、

principles

或

non-goals

。如果未指定，询问用户。

Step 2: Read Existing Document

步骤2：读取现有文档

Read the target file from

ethos/

. Present a brief summary of what's currently there.

读取

ethos/

中的目标文件。向用户简要总结当前内容。

Step 3: Read Output Templates

步骤3：读取输出模板

Read

references/output-formats.md

for the target format.

读取

references/output-formats.md

中的目标格式。

Step 4: Targeted Re-Interview

步骤4：针对性重访谈

Ask 2-3 questions focused on what might have changed:

What's different now? Present the current content summary and ask what no longer holds or what's missing.
What triggered this refresh? Understanding the motivation helps target the update (e.g., "we pivoted audiences" vs. "we changed our tech stack" leads to very different questions).

Follow up based on answers — but keep it focused. This isn't a full init interview.

提出2-3个聚焦于变化点的问题：

现在有什么不同？ 展示当前内容的总结，询问哪些内容不再适用或缺失。
触发本次更新的原因是什么？ 了解动机有助于精准更新（例如“我们切换了受众”与“我们更换了技术栈”会导向完全不同的问题）。

根据回答跟进问题——但要保持聚焦。这不是完整的初始化访谈。

Step 5: Surgical Update

步骤5：精准更新

Rewrite only the sections that changed. Preserve the user's original voice in sections that still hold. Don't reformat or rephrase content that isn't being updated.

仅重写发生变化的部分。保留用户在仍适用部分的原始表述。不要重新格式化或改写未更新的内容。

Step 6: Summary

步骤6：总结

Show what changed with a brief diff summary. Offer to adjust.

通过简要的差异总结展示更新内容。询问用户是否需要调整。

Reference Files

参考文件

File	When to Read
`references/output-formats.md`	Before generating files (init) or updating files (refresh)

文件	读取时机
`references/output-formats.md`	生成文件（初始化）或更新文件（刷新）前