cc-skill-project-guidelines-example（项目指南技能示例）Skill 是什么？如何安装？

项目指南技能（示例）：把项目架构、代码规范与部署流程一次性交给 AI

它是什么：一个面向“特定项目”的 AI 技能模板，把架构概述、文件结构、代码模式、测试要求、部署工作流和关键规则打包成 AI 可读的说明书。
解决什么问题：AI 每次新开会话都要从零解释技术栈和规范；有了它，AI 能在动手写代码前先“读懂”你的项目约定。
怎么用：既可以按原样使用，也可以把它当作模板复制一份，再把技术栈、目录结构、命令替换成自己的项目。
典型收益：减少重复交代背景的时间，降低代码风格和响应格式跑偏带来的返工，让测试与部署检查变成可执行的清单。
一个提醒：它的示例内容基于真实生产应用 Zenith（AI 驱动的客户发现平台），示例中的域名、密钥变量仅供格式参考，实际使用时必须替换。

1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？

基本信息

项目	内容
技能中文名	项目指南技能（示例）
技能英文名	cc-skill-project-guidelines-example
技能 ID	12233
作者	affaan-m
版本	1.0
定位	项目特定技能的示例模板

它解决的问题

在真实开发中，AI 编程助手最常遇到的问题是“不了解上下文”：它不知道你的前端用的是 Next.js 15 应用路由还是页面路由，不知道后端响应要用统一的 success / data / error 结构，也不知道团队要求测试覆盖率不低于 80%、单文件不超过 800 行。于是每次对话都靠人反复口头交代，既费时间又容易遗漏。

项目指南技能（示例）的思路很直接：把这些“只可意会”的项目常识，写成一份结构化、AI 可读的技能文档。AI 在针对该项目工作时先读取它，再动手写代码，从而让产出更贴近团队既有规范。

“一键安装”的思路与步骤

该技能详情中未提供具体的安装命令、仓库地址或技能市场链接，因此以下为通用流程，具体入口与命令以官方说明为准：

确认安装前提：你的 AI 编程客户端/平台需要支持“技能（Skill）”机制，能够读取技能描述文件并决定何时启用。若平台不支持技能机制，也可以直接把技能内容当作提示词或项目说明文档使用。
获取技能包：通过技能市场、团队共享目录或手动创建的方式，得到一个包含 name、description、author、version 等元信息以及正文内容的技能文件（本技能版本为 1.0）。
导入技能：按平台约定，将技能放入技能目录或通过界面导入。多数平台在导入后会显示技能名称“项目指南技能（示例）”及其描述。
刷新或重启会话：让客户端重新加载技能列表，避免新技能未被索引。
验证是否生效：新开一个会话，问一句“请根据项目指南技能，说明本项目的技术栈、前后端目录结构和 API 响应格式”。如果回答中出现了 Next.js 15、FastAPI、Supabase、Claude API、统一的 ApiResponse 结构等要素，说明技能已被正确读取；反之则需检查技能是否启用、描述是否足够清晰。

提升开发效率的关键点在于：技能只需要安装和整理一次，之后每次对话都自动复用，相当于给 AI 配了一份“长期有效的项目入职手册”。

2. 该技能的主要功能和特点

架构概述：清晰列出技术栈——前端 Next.js 15（应用路由）+ TypeScript + React，后端 FastAPI（Python）+ Pydantic 模型，数据库 Supabase（PostgreSQL），AI 能力通过 Claude API 的工具调用与结构化输出实现，部署在 Google Cloud Run，测试使用 Playwright、pytest 与 React Testing Library。同时用分层示意图表达前端、后端、数据库/Claude/Redis 的调用关系。
文件结构约定：给出前端 app/、components/（ui/forms/layouts）、hooks/、lib/、types/、config/，以及后端 routers/、models.py、main.py、auth_system.py、database.py、services/、tests/ 的目录规范，AI 生成新文件时可直接对齐位置。
可复用的代码模式：内置四个高频模式——后端统一的 ApiResponse[T] 泛型响应模型（含 ok() / fail() 构造方法）、前端 fetchApi<T> 请求封装、Claude 结构化输出调用（通过 tool_choice 强制返回符合 Pydantic 结构的结果）、React 自定义钩子 useApi 的状态管理写法。
测试要求明确：后端给出 pytest 运行、覆盖率、单文件测试命令与异步测试样例；前端给出 npm run test、覆盖率与端到端测试命令，并附组件测试示例。
部署工作流清单化：预部署检查清单（本地测试通过、构建成功、无硬编码密钥、环境变量已文档化、数据库迁移就绪）加上前端/后端的 Cloud Run 部署命令与前后端环境变量示例。
8 条关键规则：不使用表情符号、坚持不可变性不修改对象或数组、测试驱动开发先写测试、覆盖率不低于 80%、多小文件（典型 200-400 行，最大 800 行）、生产代码不写 console.log、使用 try/catch 做错误处理、用 Pydantic/Zod 做输入验证。
可当模板复用：技能本身明确说明“请将其用作您自己项目的模板”，并提供相关技能引用（通用编码规范、后端模式、前端模式、TDD 工作流），便于组合成团队技能体系。

和普通工具的差别：普通代码补全工具只看到“当前文件”，而这份技能让 AI 看到“整个项目的规矩”——包括目录该放哪、错误该怎么返回、测试要写到什么程度、上线前要检查什么。

3. 如何使用该技能？

第一步：明确适用范围

技能约定“在针对特定项目工作时参考此技能”。因此它适合作为项目级技能常驻，而不是一次性的临时提示。

第二步：以模板方式改造（推荐）

直接照搬示例只能得到一个“Zenith 项目说明书”。建议复制一份后逐项替换：

技术栈：把 Next.js 15 / FastAPI / Supabase 换成你实际使用的框架与数据库；
文件结构：按你仓库的真实目录重画；
代码模式：保留你团队真正在用的响应结构与请求封装；
测试与部署：换成你使用的包管理器、测试框架和云平台命令；
关键规则：保留仍适用的条款，删除不适用的，补充项目特有约束。

第三步：在会话中触发技能

常见调用方式是自然语言说明，例如：

“请先参考项目指南技能，再帮我实现一个查询客户列表的接口，前端也要能调用。”

第四步：给出具体需求（输入示例）

“在 backend/routers/ 下新增 customers.py，提供一个 GET 接口返回客户列表；响应必须使用技能里定义的 ApiResponse 格式；同时在前端 src/hooks/ 下用 useApi 钩子封装调用，并补一个 pytest 异步测试和一个 React Testing Library 组件测试。”

第五步：理解输出（输出说明）

理想情况下，AI 会按技能约定的位置创建文件、使用统一响应结构、给出符合目录规范的导入路径，并按技能中的测试样例风格补充测试。你应该核对：文件落位是否正确、是否使用了 ApiResponse.ok() / fail()、是否避免了直接修改对象、单个文件是否过长。

第六步：校验与迭代

按技能里的命令自查，例如后端运行：

poetry run pytest tests/ --cov=. --cov-report=html

前端运行：

npm run test -- --coverage

如发现 AI 反复偏离某条规则，说明技能描述还不够明确，应把它写进“关键规则”并补充正反例，形成闭环。

第七步：与相关技能组合

技能末尾列出了关联技能：coding-standards.md（通用编码最佳实践）、backend-patterns.md（API 与数据库模式）、frontend-patterns.md（React 与 Next.js 模式）、tdd-workflow/（测试驱动开发方法论）。项目级指南负责“本项目怎么做”，通用技能负责“这类问题怎么解”，两者搭配效果更好。

4. 同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
项目指南技能（示例）	项目级 AI 技能模板	架构、目录、代码模式、测试、部署、规则六位一体	需支持技能机制的客户端；改造需半天到一天	团队希望 AI 长期遵循同一套项目规范	优势：结构化、可复用、可当模板；不足：示例偏特定技术栈，需自行替换，内容会随项目演进过期
仓库根目录约定文件（如 AGENTS.md / 项目说明 README）	纯文档约定	用自然语言描述项目背景与规范	门槛最低，新建文件即可	轻量项目、个人项目	优势：通用、无平台依赖；不足：缺少版本与元信息，AI 不一定会稳定读取，容易被忽略
通用编码规范技能（coding-standards 类）	跨项目通用规范	命名、错误处理、可读性等通用最佳实践	一次安装，多项目复用	多项目并行、需要统一代码风格	优势：可移植性强；不足：不包含具体项目的目录结构与部署命令，缺少“本项目专属”信息
项目脚手架 / 模板仓库	代码起点生成	一键生成目录骨架与配置文件	需要熟悉脚手架命令	新项目初始化	优势：开箱即用；不足：只解决“文件从哪来”，不解决“AI 该按什么规范写代码”

选择建议：脚手架负责“搭骨架”，约定文件负责“讲背景”，项目指南技能负责“让 AI 按规范干活”。三者不冲突，组合使用收益最大；如果只保留一项，对 AI 协作效率提升最明显的是项目指南技能。

5. 该技能的典型应用场景与实际体验情况

场景一：新成员与新会话的“冷启动”

前端新人接手项目，最难的不是写组件，而是不知道页面该放 app/workspace/ 还是 components/，接口请求要不要自己写 fetch。让 AI 加载项目指南技能后提问，AI 能直接指出目录规范与请求封装方式。实际体验是：回答从“泛泛而谈的最佳实践”变成“这个项目的具体做法”，上手时间明显缩短。

场景二：前后端联调时保持响应格式一致

后端同学改了返回结构，前端同学按旧格式写解析，是联调最常见的事故来源。技能中同时给出了 Python 侧的 ApiResponse 与 TypeScript 侧的 ApiResponse<T> 接口定义，AI 生成代码时会两边对齐。实际体验：接口字段对不上的低级问题显著减少，但仍需人工确认 AI 是否真的引用了技能内容。

场景三：AI 辅助写测试并守住覆盖率

技能明确要求测试驱动开发、覆盖率不低于 80%，并给出 pytest 异步 fixture 与 React Testing Library 的写法样例。让 AI“按项目指南技能补测试”，产出的测试结构通常更贴近现有风格。注意事项：覆盖率数字需要自己跑命令核实，不能只听 AI 的描述。

场景四：部署前的自检

上线前最容易漏的是环境变量与硬编码密钥。技能里的预部署检查清单可以直接变成一次对话：“请按项目指南技能的预部署清单，逐项检查本次改动。”实际体验：把靠记忆的检查变成可复述的清单，适合作为上线前的最后一道关卡。

整体体验总结

上手难度：低。读一遍正文即可理解，改造工作量主要在于替换自家项目信息。
效果：对“规范类”问题（目录、响应格式、测试风格）帮助最明显；对纯算法逻辑帮助有限。
注意事项：示例中的域名、ANTHROPIC_API_KEY、SUPABASE_KEY 等只是格式示例，切勿把真实密钥写进技能文档；项目演进后要及时同步技能内容，否则 AI 会按过期规范写代码。

6. 该技能能为用户带来的价值

效率提升：把“解释项目背景”从每次对话都做一遍，变成只整理一次。对每天多次与 AI 协作的开发者来说，省下的是零散却高频的沟通成本。
门槛降低：新成员不必先读完整套代码再提问，AI 借助技能就能给出符合项目习惯的答案，缩短从入职到能提交第一个 PR 的周期。
质量收敛：统一响应格式、目录规范、错误处理方式与测试要求，减少代码评审中“风格不一致”的返工，让评审聚焦在业务逻辑上。
流程固化：预部署检查清单与部署命令把隐性经验显性化，降低“只有某个人知道怎么发版”的单点风险。
长期资产价值：技能文档本身就是团队知识的沉淀载体。即使将来更换 AI 工具或平台，这份结构化说明依然可以复用为项目文档、入职手册或规范基线。

7. 常见问题 FAQ

Q1：这个技能怎么安装？需要付费吗？

A：按通用流程，把技能文件导入支持技能机制的客户端或放入技能目录，刷新后新开会话验证即可；具体入口与命令以官方说明为准。技能详情中未标注价格信息，是否收费同样以官方说明为准。若平台不支持技能机制，也可以直接把内容作为项目说明或提示词使用。

Q2：它适合谁用？个人开发者用得上吗？

A：最适合三类人：一是维护中大型项目的团队，需要 AI 稳定遵循同一套规范；二是频繁与 AI 结对编程的开发者；三是正在搭建团队 AI 技能体系的技术负责人。个人小项目也可以用它当模板，把架构和规则压缩成精简版，收益同样存在。

Q3：我的技术栈不是 Next.js + FastAPI，还能用吗？

A：能。技能本身定位就是“示例模板”，它的核心价值是示范“一份好的项目技能该包含哪些部分”：架构、目录、代码模式、测试、部署、规则。你只需保留结构、替换内容，把技术栈、目录树、命令和检查清单换成自己的即可。

Q4：装了技能，AI 就一定会照着做吗？

A：不一定。技能是“强提示”而非“强制约束”，AI 仍可能遗漏个别条款。实践中建议：关键规则写得越具体越好（最好附正反例）、在需求中显式说“请参考项目指南技能”、产出后用测试命令和清单人工核对。

Q5：它和通用编码规范技能、项目模板仓库怎么选？

A：三者解决不同层次的问题。模板仓库解决“项目骨架从哪来”，通用编码规范技能解决“这类代码怎么写更好”，项目指南技能解决“在这个项目里该怎么写”。推荐组合使用：新项目先用脚手架起步，再补一份项目指南技能，最后叠加通用规范技能。