AI Coding需要Agent.md,AI Product需要Design Skill.md——Designer Skills for Claude Code & Cursor from Julian Oczkowski

一、什么是Agent.md

AI 每天都在飞速发展，从Promot到Agent，再到Skill。不管是现在的Harness Engineering，还是之前的 Vibe Coding，都是需要用Agent.md去进行AI 编码行为约束。

Prompt是单次手动输入的指令，用来进行局部需求输入。Agent.md相当于一次性写好，自动生效的项目说明书，服务于整个项目声明周期。

Agent.md通常包含七个部分，覆盖「先想后做 → 简洁优先 → 外科手术式改动 → 目标驱动执行 → 验证后再声明完成 → 尊重已有工作 → 沟通风格」

💡AGENT.md

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

Tradeoff:These guidelines bias toward correctness, clarity, and small diffs over raw speed. For trivial tasks, use judgment.

1. Think Before Coding

Don't assume silently. Surface assumptions and tradeoffs.

Before implementing:

State important assumptions explicitly when they affect the solution.
If multiple interpretations exist and the wrong choice would cause rework, data loss, security risk, or user-visible behavior changes, ask before editing.
If a reasonable, low-risk assumption can be made from local context, proceed and mention it.
Prefer the simpler approach unless the codebase clearly needs a broader one.
Push back when the requested approach is likely to cause bugs, unnecessary complexity, or maintenance cost.
Don't hide confusion. If local context is insufficient and guessing would be risky, name what is unclear and ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

No features beyond what was asked.
No abstractions for single-use code.
No flexibility or configurability that was not requested.
No error handling for impossible scenarios.
Prefer boring, direct code over clever code.
If the solution becomes much larger than expected, pause and reassess whether there is a simpler path.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

Touch only what is necessary. Clean up only your own mess.

When editing existing code:

Don't improve adjacent code, comments, naming, or formatting unless required for the task.
Don't refactor unrelated code.
Match the existing style, even if you would normally write it differently.
If you notice unrelated dead code or design issues, mention them instead of changing them.
Avoid broad rewrites unless the request specifically calls for one.

When your changes create orphans:

Remove imports, variables, functions, files, or tests that your changes made unused.
Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

"Add validation" -> "Write or update tests for invalid inputs, then make them pass."
"Fix the bug" -> "Reproduce the bug with a test or command, then make it pass."
"Refactor X" -> "Preserve behavior and run the relevant checks before finishing."
"Change UI" -> "Verify the changed state visually or with an appropriate browser/test check."

For multi-step tasks, use a brief plan:

1. [Step] -> verify: [check]2. [Step] -> verify: [check]3. [Step] -> verify: [check]

Strong success criteria let you work independently. Weak criteria require clarification.

5. Verify Before Claiming Done

Don't declare success without evidence.

Before finishing:

Run the narrowest relevant test, build, typecheck, lint, or command available.
If no automated check exists, perform the most direct manual verification available.
If verification cannot be run, say exactly why.
Report what was checked and what remains unchecked.
Don't imply the entire project is healthy if only a narrow check was run.

6. Respect Existing Work

Never overwrite user work casually.

When working in a repository:

Check the current state before making edits when practical.
Treat unrelated changes as user-owned.
Do not revert, delete, or reformat changes you did not make unless explicitly asked.
If user changes conflict with the task, explain the conflict and ask how to proceed.
Keep generated files, lockfiles, snapshots, and formatting churn out of the diff unless needed.

7. Communication Style

Be concise, concrete, and useful.

While working:

Explain what you are doing and why when the task is non-trivial.
Prefer concrete file names, commands, and outcomes over vague status updates.
Surface risks early.
Avoid excessive narration for simple tasks.
Don't overpromise. Say what is known, what was changed, and what was verified.

Final response should include:

What changed.
How it was verified.
Any limitations, skipped checks, or follow-up risks.

可以看出来，这是从产品角度提出的Agent.md架构。对于开发者角度，简答的说则是至少包含五个部分：

💡项目背景——AI 需要知道这是什么项目，否则它没有上下文做判断：

**项目简介

这是一个面向新加坡中小企业的 SaaS 财务管理系统。

后端用 FastAPI + PostgreSQL，前端用 React + TypeScript。`

技术规范——告诉 AI 用什么技术栈、禁止用什么：

**技术规范

-Python 3.11，使用 Pydantic v2（禁止用 v1 语法）

-所有 API 端点必须有 OpenAPI 文档注释

-禁止使用 requests 库，统一用 httpx

代码风格——让 AI 生成的代码风格与项目一致：

**代码风格

-函数命名用 snake_case，类名用 PascalCase

-所有函数必须有 docstring

-错误处理统一用自定义 AppException，不要裸 raise

目录结构——让 AI 知道在哪里创建文件：

**目录结构

src/

api/ *FastAPI 路由

services/ *业务逻辑

models/ *数据库模型

schemas/ *Pydantic 模型

tests/ *测试文件，与 src/ 镜像结构

行为约束——控制 AI 的操作边界：

**行为约束

-修改数据库 schema 前必须先询问确认

-不要自动删除任何文件

-每次改动后运行 pytest，确保测试通过

Claude code专业开发手册2.0作为Anthropic官方发布的Coding手册，内容则更为丰富，直接包含八个章节：

AI 编程方法论
Claude Code工具体系
工程实践
工程化能力
团队协作
架构设计
SaaS实战案例

如有需由，私信我，发您对应的.md文件

二、什么是design skill.md

AI目前应用最广，最有效的行业，一直都是编程，特别是专业的编程。对于个人提效非常有帮助。甚至已经团队级的协作提效。

除此之外，AI也让编程能力的下限不断降低，特别是像Vibe Coding，给人一种言出法随的感觉。Vibe Coding主要用于产品经理的原型搭建和demo模拟，旨在进入开发阶段前，验证需求或者交互的合理性及可行性。也可用于个人爱好者，进行一些独立小应用的产出。但产品开发毕竟是一个很严谨的过程，独立应用的开发，更像是小垂类的不断细挖，针对垂类用户需求的精准打磨。很多人说自己靠一个人手攒一个价值几百万的管理系统，其实是极大的夸大了编程结果。系统不是产品，里面的嵌套逻辑非常复杂，抛开接口不说，将所有逻辑写进prd里，都至少需要几百页。一个公司级的系统产品，靠一个人用AI进行手攒，肯定是不显示，也几乎不可能的。

但是对于原型搭建和demo模拟，则非常靠谱，因为本身就有完整的需求文档和设计实现，通过AI进行快速demo输出，非常合理。那怎么才能保证这个结果更好呢，可以试试Julian Oczkowski大神提出的design skill，虽然是为设计师提出的AI Skill，但对于产品经理，同样适用。

如果需要这个skil文件，也可以私信我，大家也可以从中参考AI Coding的思路，很值得借鉴。

/design-flow

按引导顺序运行完整工作流程。它会按顺序协调所有技能，允许您跳过某些阶段，并在每个步骤之间进行确认。如果您想体验完整流程，请从这里开始。

2./grill-me

你的计划会被反复盘问，直到每一个设计决策都得到解决。

3./design-brief

将问答环节转化为结构化的设计简报。包括代码库探索，以便人工智能能够尊重现有代码。

4./information-architecture

定义结构框架：导航、内容层级、页面结构、URL 模式、用户流程。

5./design-tokens

根据所选的美学理念，生成包含浅色和深色模式调色板的完整标记系统（颜色、间距、字体、动态效果）。

6./brief-to-tasks

将简报分解成一个有序的清单，清单中包含可独立构建的垂直切片。

7./frontend-design

秉承一套明确的美学理念进行构建。移动优先。包含深色模式。8 项设计理念，并附有具体的实施参数。

8./design-review

对项目简报进行结构化评审。支持代码审查和基于屏幕截图的审查。按需运行，而非自动运行。请在完成项目构建后使用。

以上8个skill的md文件，第一个用来加载skill流程，其他七个，用来执行对应的skill。对应的md文件内容很详细。后面可以发给大家自己进行阅读和学习。

Grill me 让AI反复询问需求

这是我觉得最好用的一个skill，当用户告诉AI，要Coding一个具体什么样的产品时，AI开始询问用户具体的产品需求方向。

这可以帮助AI获取足够多的信息，防止用户的一句话需求，信息不够以支撑AI进行思考。这个阶段一般可以进行四轮问询，即是给AI提供信息输入，也是帮助产品经理或设计师自己思考。了解需求背景，搞清楚产品的用户群、核心交互、定位、商业模式、关键场景、核心功能、优先级等关键问题。

Design Brief 设计概述

和Grill me类似，Design Brief也是通过询问你，来获得基础的产品需求。到了这一步的产出已经包含很多的信息了，包括大的视觉风格、组件库、核心区域组件、用户操作路径等等。

JTBD 的主要用户是谁？他们想要实现什么目标？
对于这个界面来说，成功的标准是什么？
情感基调是什么？（平静、急迫、轻松、权威、温暖、冷静）
它应该像哪些现有的产品、网站或风格？它不应该像哪些现有产品、网站或风格？
有哪些硬性限制？（设备、无障碍要求、性能预算、品牌指南）
这个界面将包含哪些内容？哪些是占位符，哪些是实际内容？

Information Architecture应用架构

在视觉设计开始之前，定义产品或网站的结构层。这包括导航、内容层级、页面结构、URL模式和用户流程。这一步不用太多操作，基本上是根据上面两步，自动总结生成对应的信息。

这点非常适合刚做产品经理，或者产品经验不是很多的朋友。

AI根据Skill可以自动生成完整的应用架构，有哪些页面，页面对应的层级，页面的信息构成，以及完成的用户流程。

这可以很大程度的保证Coding结果的可用性，保证一定的用户体验。可以说是AI帮用户实现了上帝视角，去更全面的思考应用或者网站应该是什么样子。

Design Token设计物料

通过skill自动生成，明确产品或网站的UI设计风格

这也是很容易忽略的一点，产品经理对设计风格并不了解。可能给了一个参考图，但是对于AI，并不一定能够完全理解你想表达的意思。有了Design Token就可以完全展示出设计风格，提前沟通就事半功倍。

包含页面排版，字号，颜色，间距，布局，甚至动效等等信息

Brief to task 项目管理

这个skill对于没有编程经验的朋友很好用，AI根据前面的产品需求，自动拆解成子任务去执行，保证项目正式顺利推荐。防止用户无头绪，使得需求混乱，干扰AI的Coding结果

1. 将工作分解成若干垂直部分。每个任务应该：

能够独立构建（除非另有说明，否则任何任务都不应阻塞其他任务）。
将结构、样式和交互包含在一个任务中（而不是“构建 HTML”、“添加 CSS”、“添加 JS”作为单独的任务）。
确保结果可验证：您可以查看结果并确认其符合要求。
篇幅要足够小，以便在一次课程中完成。

2.按以下方式排序任务：

首先处理依赖项：在进行页面特定工作之前，先处理基础元素（令牌、布局外壳、共享组件）。
视觉优先级：最突出的 UI 元素应尽早显示，以便用户在投入细节之前验证美学方向。
风险优先：尽早承担最困难或最不确定的部分，以便在其他一切都围绕问题构建之前，问题就会显现出来。

Frontend Design 前端设计

到了这步，就可以通过这个skill直接输出原型了

你也可以选择一些视觉风格

💡迪特·拉姆斯（功能主义者）

少即是多，每个元素都各司其职，没有华而不实的装饰。

字体：简洁的无衬线字体（Helvetica Neue、Suisse Intl、Akkurat）。标题字间距紧凑。正文行高宽松。统一字号，严格使用。
色彩：克制。单色调，仅以单一功能性元素点缀。白色或浅灰色背景。色彩是信息，而非装饰。
布局：严格的网格结构。清晰的功能层级。组件与空间系统对齐。不为不对称而不对称。
间距：统一的数学比例（基准4px/8px）。充足的内边距。元素之间留有呼吸空间。
动态效果：极简。仅包含有意义的过渡效果（状态改变、揭示）。无装饰性动画。
细节：阴影上方有细微的边框和分隔线。精确的对齐。圆角使用得恰到好处，且风格统一。

瑞士/国际印刷

通过结构实现客观性。网格是神圣的。内容为王。

字体：醒目的无衬线字体（Neue Haas Grotesk、Univers、Aktiv Grotesk）。标题和正文之间采用鲜明的尺寸对比。副标题全部大写，字间距较大。
颜色：高对比度。黑色、白色和一种原色。醒目的色块作为构图元素。
布局：严格的多列网格。非对称平衡。文本和图像以对话形式呈现。元素间的对齐方式不容更改。
间距：由网格模块定义。排水槽是设计的一部分，并非事后添加。
动态效果：页面过渡和滚动触发的显示效果均遵循网格布局，无弹跳效果。
细节：以线条（水平线）作为结构元素。没有渐变。没有阴影。平面性是关键。

日本极简主义（Ma）

留白亦是内容。克制彰显优雅。静谧胜过喧嚣。

字体：纤细的无衬线字体或优雅的衬线字体（例如 Noto Sans、Cormorant）。行高适中（1.8-2.0）。字号较小，留白较大。
色彩：柔和的自然色（暖灰色、石色、鼠尾草绿、和纸绿）。强烈的对比之下，色调变化微妙。接近单色。
布局：不对称但平衡。内容偏离中心。大片空白区域是刻意留白。内容仿佛漂浮在空间中。
间距：极致留白。内边距和外边距是“正常”水平的 2-3 倍。元素之间留有呼吸空间。
动态效果：缓慢柔和的淡入淡出（400-600毫秒）。无弹跳，无过冲。透明度过渡与位置变化同步。
细节：纤细的边缘。微妙的纹理（纸张纹理、亚麻布纹理）。无明显的阴影。柔和、漫射的效果。

粗犷主义/原始

结构清晰可见，未经修饰。反美学即美学。

字体：系统字体、等宽字体（JetBrains Mono、IBM Plex Mono、Courier）或醒目的展示字体。混合字号。文本纹理。
颜色：以黑白为主。如果使用其他颜色，则应使用鲜艳刺眼的颜色（例如施工黄、警示橙、终点绿）。不使用渐变色。
布局：可见的边框。外露的盒模型。堆叠的模块。刻意营造的粗糙感。内容至上，美观次之。
间距：过紧或故意不均匀。衬垫感觉被压实。
动态效果：无，或突兀（瞬间状态改变，硬切）。无缓动效果。
细节：可见轮廓。默认浏览器表单元素可能是有意为之。纯文本界面。除非功能性需要，否则不使用图标。

斯堪的纳维亚语

温暖而内敛。功能性与美感兼具。默认可用。

字体：圆润友好的无衬线字体（Nunito、Poppins、Circular、Cera Pro）。中等字重。舒适的阅读尺寸。
颜色：自然色调。暖白色、柔和的蓝色、淡绿色、陶土色。粉彩色调点缀。不使用纯黑色（使用炭灰色）。
布局：简洁明了，卡片式设计，圆角（8-12像素），舒适宽敞的布局。
空间布局：宽敞但不局促。一切都显得平易近人且简洁明了。
动态效果：轻柔自然的缓动。微妙的悬停提升。内容缓缓落入到位。
细节：柔和的阴影（大范围模糊，低不透明度）。圆润的元素。灰色调偏暖。适合插画创作。

装饰艺术/几何

大胆的对称设计。装饰性的精准。彰显个性与奢华。

字体：几何图案标题字体（Futura、Poiret One、Josefin Sans）。标题采用全大写字母，字间距极大。正文采用衬线字体，形成对比。
颜色：浓郁深沉。金色/香槟色、祖母绿色、海军蓝、勃艮第酒红色、黑色。金属光泽（金色渐变、闪光效果）。
布局：对称居中。强烈的垂直轴线。装饰性的边框和纹饰。层次丰富的视觉效果。
间距：结构化且正式。填充物具有建筑美感。
动态效果：优雅的揭示。错落有致的入场动画。视差深度。
细节：几何图案（人字纹、放射状图案、扇形图案）。装饰性边框。纹理（大理石、拉丝金属）。醒目的大字字体。

新孟菲斯

嬉戏般的混乱。反企业。形状即角色。
字体排版：混合使用多种字重和样式。故意使用冲突的字体。超大标题。倾斜的文本。
颜色：鲜艳的原色和霓虹色。对比强烈的色彩组合（粉色和黄色，蓝色和橙色）。没有柔和的色调。纯色，没有渐变。
布局：打破网格。元素重叠。形状（圆形、三角形、曲线）作为构成元素。刻意采用不对称设计。
间距：部分区域密集，部分区域稀疏。节奏不规则。
动态效果：活泼、生动。夸张的悬停效果。元素会摆动、旋转或弹出。
细节：粗边框。几何图形作为装饰。图案（点、线、锯齿线）。带有硬边和鲜艳色彩的阴影。

社论/杂志

内容主导设计。排版才是关键。每一页都是跨页。
字体：标题使用衬线字体（Playfair Display、Fraunces、Instrument Serif）。正文使用简洁的无衬线字体（DM Sans、Source Sans）。醒目的尺寸（主标题72-120像素）。引用。首字下沉。
颜色：极简主义。黑白配色，略加一点点缀。色彩运用仅用于编辑目的（突出重点，而非装饰）。
版式：严格的列网格（3-5列）。全出血图片。文本自动换行。混合列宽。垂直韵律。
间距：宽裕的页边距。标题行距紧凑，正文行距宽松。留白作为一种构图工具。
动态效果：滚动触发式显示。图像视差效果。流畅的页面过渡。
细节：细线作为分隔线。标题字体。期号/日期元数据。印刷风格的细节（页码、页眉）。

实施指南

字体选择：选择通过 Google Fonts 或 CDN 加载的独特字体。避免使用通用默认字体（例如 Inter、Roboto、Arial 和系统字体）。标题字体与正文字体搭配使用。
颜色：使用 CSS 变量以保持一致性。主色调搭配鲜明的点缀色比安全、均匀分布的调色板效果更好。
动态效果：HTML 的 CSS 过渡效果。Framer Motion / React 的动态效果库。专注于高冲击力时刻（页面加载揭示、状态变化），而非零散的微交互。
空间构成：出人意料的布局引人注目。不对称、重叠、对角线走向、打破网格的元素。或者，如果设计理念需要，也可以采用精确执行的严格网格。
背景和景深：营造氛围。渐变网格、噪点纹理、几何图案、分层透明效果、颗粒叠加。与所选理念相符。

Design Review设计检查

最后这步，skill是把AI Coding的结果的每个页面进行截图，让AI来自己评估设计的好坏。

与设计简报的美学方向进行比较

检查视觉层级：最重要的元素是否最突出？

检查间距一致性：边距和内边距看起来是否均匀且符合设计意图？

检查颜色：配色方案是否符合设计简报的要求？

检查字体排版：字体大小、粗细和间距在视觉上是否正确？

检查响应式适应性：布局是否正确重新组织（而不仅仅是缩小）？

注意仅凭代码审查无法发现的渲染问题（字体加载失败、图像损坏、布局溢出、z-index 问题、边框圆角不正确、颜色不匹配）

这对于不太懂视觉设计的朋友比较友好，可以通过AI来完成设计的优化。

三、总结

虽然这套Skill并不一定能保证产出的效果最好，但是他的思路是很好的，可以让大家在AI Coding辅助原型输出过程，让自己的结果能更好的接近自己想要的表达。

我是久歌。

👁我，一起学习AI。

一、 什么是Agent.md