ARTICLE · 1080588
本周收藏了些什么10 | 文档写作、写AGENTS、清理skill、100个问题系列丛书、求职skill、人物一致性等
阮一峰的《中文技术文档的写作规范》
与其写一堆约束规则给AI，不如给AI一个优秀的示范。这里推荐阮一峰大佬的这份《中文技术文档的写作规范》，用简短规则和正反示例，说明如何组织章节、写清句子、统一排版。
如果需要写技术文档、技术方案都值得一看，不仅仅是给AI看。 项目地址： https://github.com/ruanyf/document-style-guide
同时，还有人基于此做出了技术文档写作skill，一个写中文技术文档的 Agent Skill。用它写 README、设计文档、接口说明和教程，读起来像工程师写的，没有 AI 腔。
效果：
下面是一段常见的 AI 写法：
随着微服务架构的不断发展，配置管理已经成为一个不容忽视的问题。值得注意的是，ConfigHub 不仅提供了强大的配置管理能力，更实现了与现有系统的无缝集成——让你轻松应对各种复杂场景！
用这个 skill 以后：
ConfigHub 用来集中管理多个服务的配置。修改配置后，服务会在 5 秒内加载新值，不用重启。接入时，在启动命令里加上
--config-hub=<地址>即可。
项目地址： https://github.com/leter/zh-tech-writing
关于AGENTS.md
本周Claude也宣布支持 AGENTS.md 了，大势所趋之下，如何写好自己项目中的AGENTS.md 就很关键了。
AGENTS.md 不是一份越写越全的说明书。项目里的文件指向总入口，总入口再告诉 Agent：这次做什么，该去读哪份规则。复杂任务可能要读好几份，那就读；没碰上这类任务，就别每次开工都让它先看一遍。
”这是每次都要交代的事，还是只有做这件事的时候才需要？“
原贴：https://x.com/rwayne/status/2102732096909537515
看到了大佬分享的模板，可以借鉴：
## 项目介绍
<!-- 请介绍你的项目：面向哪些用户、解决什么问题、包含哪些核心功能，以及功能之间的关系，补充必要的业务术语和职责边界。 -->
## 总体原则
### 最高原则
- **术语约束**：使用项目已有的术语，不允许推测或造词。
- **编程思考**：运用第一性原理思考，拒绝经验主义和方案盲从。不要假设我完全清楚目标，从原始需求和问题出发。若目标模糊，请停下来和我确认；若目标清晰但路径非最优，请直接建议更短、成本更低、可读性更好、更易维护的方案。
- **简洁优先**：用最少的代码解决问题。只回答用户实际问的问题，精准、简洁，必要扩展必须服务于原问题。
- **精准修改**：只碰必须碰的，只清理自己造成的混乱。不要重构没坏的东西，不要改进相邻的代码、注释或格式，除非得到用户许可。
### 常用约束
- **OpenSpec 一致性**：本项目代码开发通常使用 OpenSpec 工作流，相关文档位于 `openspec/changes/<change-id>/`，包含 `proposal.md`、`design.md`、`tasks.md` 和 `specs/*/spec.md`。代码改动若与 OpenSpec 文档相关，必须同步更新文档，保持文档与代码一致。
- **代码设计**：避免修改入参的副作用，方法内不允许修改入参字段的值。
## 技术栈
- Java、Spring Boot、微服务框架、RPC、分布式数据库、RocketMQ、 MyBatis、Redis 缓存、分布式任务调度、Maven 多模块。
## 架构
### 模块结构
| 模块 | 说明 |
|------|------|
| 业务领域模块 | 按子领域划分，采用 DDD |
| 基础设施模块 | 防腐层、持久化、配置、通用工具类、外部服务调用 |
| 业务编排模块 | 遗留业务编排层 |
| API 模块 | 发布的 API 制品 |
| 启动模块 | Spring Boot 应用入口 |
### 领域模块
#### 子领域模块
<!-- 请列出你的项目实际包含的子领域模块，说明各模块的名称、目录、职责和边界。对遗留模块、临时模块或限制修改的模块，明确标注。 -->
#### 每个子领域模块包含
- `application/`：RPC 适配层、消息消费适配层、定时任务适配层、应用服务层，以及跨领域防腐层接口的实现。应用服务层负责编排多个领域服务。
- `domain/`：业务逻辑。
- `extension/`：扩展点。
### 架构约束
1. **调用链路**：通常为 RPC、消息消费或定时任务接口适配层 → 应用服务层 → 领域服务层 → 仓储层 → DB Mapper。
2. **依赖反转**：子领域模块之间不直接依赖，通过防腐层解耦。接口定义在基础设施模块，接口实现在对应领域模块的应用层。
3. **同层不依赖**：App Service 不能直接引用其他 App Service，Domain Service 不能引用其他 Domain Service，Repository 之间也不能相互引用。
4. **基础设施集中**：消息队列、任务调度、外部防腐、配置管理、开关、对象存储、数据库等基础设施统一放在基础设施模块。
## 日志
- 项目使用 Logback 日志框架，志配置位于启动模块的 `logback-spring.xml`。
- 打印 debug、info、warn 日志时，优先使用项目统一的日志工具类。
## 关键文件
| 文件或配置 | 用途 |
|------------|------|
| 启动模块中的应用入口类 | 应用启动 |
| `application.properties` | Spring Boot 配置 |
| 功能开关配置类 | 功能开关 |
| 规则文件位置| 某一类用户规则文件 |
## 验证
- 单元测试规范：遵循项目内的单元测试规范文档，引用单元测试文档位置
原贴： https://x.com/uudonX/status/2097591420567867841
定期清理skill
当AI能力越来越强，比如这周opus5.5 又站起来了，很多之前写的约束或者规则，甚至skill，反而会限制或者影响AI产出。
当AI能力越来越强，就越需要定时清理skill，不要过分依赖skill。
只有模型和巴菲特都不知道的知识，才用 Skill。
多与AI讨论沟通，让AI更详细的了解，你想做什么，为什么这么做，想达到什么目的，AI掌握了这些信息后，自然会更清楚如何实现。这可比直接调用一个被人写死的skill强很多。
原贴： https://blog.joway.io/posts/ai-coding-principle/
出如何做好文档管理
看到宝玉大佬分享做文档管理，值得借鉴：
1. 文档统一放 docs 目录 2. 所有文档都遵循渐进式披露原则——也就每个文档都不大，但是会链接到相关文档，类似于主文档里面主要就是概要和目录，具体内容链接到章节对应的小文件 3. 根目录有一个 README 可以方便的索引到相关文档，类似于目录 4. AGENTS.md 强制要求修改功能要修改相关文档，有时候人也需要定期检查一下，即使加了规则也可能遗漏
渐进式披露给AI很关键，做好索引，让AI自己根据需要检索读取，而不是一股脑喂给AI。
原贴： https://x.com/dotey/status/2102415020021756020
一本开源书：深入理解AI Agent
这个项目之前就开源在GitHub上了，作者此次贴心的做成了一个网站，方便查询和跟练。
网站： https://bojieli.github.io/ai-agent-book/astro/
AI磊叔出品的《100个问题》系列丛书
这个非常推荐。
目前的内容已经覆盖了AI技术讲解、AI工具讲解、AI赋能和职业发展，截图举例下：
通过问题和回答的方式，让我们更快的找到并解决自己的疑惑，希望这个系列可以一直更新下去。
飞书文档： https://my.feishu.cn/wiki/FC6ZwnwWWi0dWpke56act61gnUd
生图技巧之人物一致性控制
人物一致性控制是打造IP必备技能，本质上是一张角色视觉定义图，把脸、身材、发型、表情、服装和不同视角一次性固定下来。
可复用的提示词：
【任务】
基于参考图生成一张高精度角色设定板(Character Sheet)锁定角色ID，不允许生成新角色，所有画面必须基于同一角色结构
【基础设定】
风格:[写实3D/风格化3D/动漫/半写实/IP设计]
角色描述:[填写你的角色描述或上传参考图]
性别:[男/女/中性]
年龄:[数值]
体型:[瘦/标准/健壮/夸张比例]
风格关键词:[高级感/时尚/潮流/科技感/情绪化等】
【画面结构】
- 画面比例:4:3横版
- 背景:纯白/米白/极简
- U1:干净技术排版,无logo,无水印
- 字体:清晰可读英文标签
【必须包含模块】
1. 顶部信息
- 名字(可自动生成)
- 角色身份
- 年龄
- 性格关键词(3-5个)
- 核心主题(1句)
2. 配色系统-6~8个色块(无文字)
3. 主身份展示(最大区域) 重点:锁定角色
- 正面/3/4/侧面/背面
- 标准站姿
- 带比例线(身高刻度)
- 无道具
4. 轮廓剪影
- 正面剪影
- 侧面剪影
5. 表情系统(8张)
- 平静/好奇/紧张/惊讶/害怕/悲伤/坚定/放松
6. 微表情(5张)
- 眼部紧张/微笑/嘴部用力/微恐惧/呼吸控制
7. 头部结构
- 多角度(3/4/侧面/仰视/俯视)
8. 姿态变化
- 放松/紧张/自信
9. 特写镜头(1张)
- 胸部以上
- 强情绪表达
10. 服装细节(4张)
- 发型/材质/配饰/鞋
11. 手部动作
- 放松/紧张/指向/抓握/面部动作
【一致性要求】
- 所有画面角色完全一致(脸/发型/比例/服装)
- 不允许风格漂移
- 主展示区域必须最大【质量要求】
- 0G级细节
- 材质真实(皮肤/布料/金属)
- 影视级光影
原贴：https://x.com/leo_xiaolei/status/2102013053084545433
有意思的网站分享 Read Something Wonderful
这是一个主打高质量、慢节奏深度阅读的精选内容推荐网站。
以“经典耐读”替代“时效追新”。
与社交媒体、新闻聚合器追逐即时热点不同，该网站专门收集互联网上有深度、耐人寻味、具有长久价值的长篇好文与随笔。
页面设计极度克制、清爽，没有杂乱的信息流与广告。
每次进入或刷新网站时，它通常会像“I’m Feeling Lucky”一样为你随机展示一篇深度内容，帮助读者跳出算法信息茧房。
内容涵盖科技、文化、哲学、商业洞察、设计与个人成长等领域，精选了诸多知名作者与思想者的经典之作。
值得翻阅： readsomethingwonderful.com
skill推荐：求职找工作skill合集
https://github.com/yanliudesign/offer-toolkit-skill
0 还在找机会 → job-hunt-skill 批量发现、去重、生成可搜索清单
1 看到心动岗位 → job-description-skill 解码 JD、出一份 Offer Strategy 报告
2 决定投 → resume-skill 改简历、11 套打印级模板
3 拿到面试 → bq-skill 挖故事、建故事库、准备 BQ
4 拿到多个 offer → offer-compare-skill 对比 TC、成长与风险，给明确推荐
5 准备签 offer → salary-negotiation-skill 诊断杠杆、生成话术、明确停止线
AI使用小技巧
日常里，看到优秀的方法都会记录下来。比如，这周发现的：
原句：use big pictures and few words
直译：多用大图，少写文字。
说话人是重度 AI 用户，每天多次给 AI 输入这句提示词，核心诉求：
希望 AI 输出可视化图表 / 大图为主，文字精简，不要长篇大论纯文本；
厌倦 AI 大段啰嗦文字，偏好图文结合、视觉化的结果；
属于提示工程（写 prompt）里的常用指令，用来约束 AI 的输出形式。
一句话总结：这是用户反复给 AI 用的提示词，要求 AI 少文字、多用大幅图示来表达内容。
做一个通用 Prompt：
对下面的问题不要进行泛泛解释。
先进行问题重构，识别其中的隐藏假设和关键变量。然后分析其底层机制和因果链，说明成立所需要的前提条件和边界条件。
同时寻找反例、替代解释和失败模式，指出主要 trade-off。
区分事实、公开宣称、合理推断和假设。
最后分析其一阶影响、二阶影响和长期反馈效应。
很多时候，这比一句：
“请深入思考。”
有效得多。
agent 原生开发（翻译：一行代码不会写）的最佳实践：
> “砂锅大法”（打破砂锅问到底）
也就说，和 agent 讨论方案，有任何自己不理解的地方一直问，不断提供更多 context，直到自己确认理解了 agent 在做什么，如何解决你的 issue，然后才放手让 agent 执行。
对立面：自己不理解，无脑让 agent“继续继续”……即使是 fable 模型，在开发的时候也不避免会引入次优、甚至错误的方案。长期“继续”下去，就会出现拆东墙补西墙、按下葫芦起了瓢的问题，最后难以为继，大幅度偏离。
OK，这就是本周的收藏，也祝大家节日快乐~ 你最近发现了哪些值得长期保存的网站、文章或项目，也欢迎评论区留言~