KKKKhazix/khazix-skills / neat-freak
neat-freak
Unverified干完活的知识收尾:把项目文档、CLAUDE.md/AGENTS.md 等规则文件、Agent 记忆和会话留下的临时文件,对齐到代码和线上的真实现状,让下一个会话或接手的人读到的是唯一、正确的现役答案。触发:用户点名 "neat-freak"、"洁癖"、"/neat",或明确的知识收尾意图——开发后同步文档与记忆、CLAUDE.md/记忆过期或冲突、交接前清场、审计规则是否被遵守("把文档和记忆整理一下"、"docs 和代码对不上了")。不触发:纯写代码/重构/调试、整理数据或文稿(JSON、周报、changelog)、没有项目知识语境的裸"整理"。
references/sync-matrix.md
View on GitHub# 哪类改动会波及哪些文档
这张表用来提醒你该去查哪里,不是让你按它新建文件。先看项目现有的架构、接入、运维和发布文档各是哪几份,再把对应读者要看的那份改到位。
## 代码或线上变了,该查哪些地方
| 变了什么 | 要核对的地方 |
|---|---|
| 接口、路由、协议 | 给外部的接入说明、架构里的路由、鉴权说明、示例、下游项目的文档、冒烟测试 |
| 环境变量、服务商、模型 | 示例 env、运维手册、默认值写在哪、下游配置、成本和回退说明 |
| 数据库结构、存储字段 | 数据模型说明、迁移与回滚、派生数据和缓存、读写边界、测试 |
| 用户流程、权限、导航 | README 和产品说明、架构里的权限、运营手册、界面验收 |
| 评分、筛选、聚类、提示词 | 现役算法的文档、阈值和开关、回测结果、回退方案、对展示的影响 |
| 服务、部署、CDN | 运维手册、服务名、版本标记、缓存、回滚、线上验收 |
| 后台任务、告警 | 任务文档、调度、失败怎么收口、告警发给谁 |
| 退役、改名、下线 | 用旧名字搜一遍:下游、规则文件、Skill、记忆里的非历史引用都要改;明确标注为历史的保留 |
| 发布流程、多个 Agent 的协作方式 | 流程文档、合并和部署脚本、清场前的检查 |
## 四种读者要看的东西
新增或改变一个能力时,判断下面四件事在这个项目里各由哪份文档承担。不要求有四个固定的文件,一份文档兼几件事就在那一份里改。
1. **怎么用**:README、接口或接入指南、示例。
2. **怎么工作**:架构、数据结构、状态流转、设计边界。
3. **怎么运维**:运维手册、环境变量、冒烟测试、回滚、告警。
4. **当前状态和历史**:发布说明、事故记录或 git。项目规则或用户明确要求时才写 changelog。
## 该先删的东西
| 常见的噪音 | 默认怎么处理 |
|---|---|
| 规则文件顶部塞着「某日 X 上线,详见 Y」 | 还在生效的约束并进正文;纯历史交给 git、changelog 或事故记录 |
| 规则文件里抄了完整的架构、公式或数据流 | 只留边界和一句指向权威文档的话,细节放回 docs |
| 好几个版本都自称「现役」 | 用代码开关、线上状态和回退关系裁决;旧版本明确标为回退或已退役 |
| 已完成的待办还列在开放项里 | 核实后删掉,或改写成现在的约束;不留「已完成」的流水账 |
| 一次事故的长篇经过常驻记忆 | 提炼出以后用得上的教训;机制进 docs,过程进事故记录或 git |
| 同一条规则抄了好几处 | 留一处讲全,其他地方放一句指针或删掉 |
| 「留着当历史」却没人会读 | 删掉。要留的历史得有用途、有固定位置、找得到 |
| 会话留下的计划文档、调试脚本、`xxx_old` 和 `xxx_backup` 副本 | 有效内容并进正式文档;文件列为删除候选,授权范围内清理,没授权就问 |
## 记忆怎么分流
| 记忆里的内容 | 怎么处理 |
|---|---|
| 用户偏好、被反复纠正的做法 | 平台允许、用户也同意时,留成短的、能照着做的条目 |
| 系统怎么工作 | 并进权威文档;记忆里只留一句指针 |
| 做过的决定 | 只留最后的结论和仍然成立的理由;过程交给 git 或 changelog |
| 已完成的开放项 | 核实后删掉,不让它继续冒充计划 |
| 相对时间 | 讲当前状态的改成绝对日期;讲历史的自然说法不机械替换 |
| 重复或互相冲突 | 用当前代码和线上状态裁决;裁决不了就保留冲突,在汇报里说明 |
| 机器生成的索引 | 不直接编辑;走平台规定的入口,交给它自己重新生成 |
| 很久没被引用 | 结合它是否权威、以后是否还用得上来判断;没人引用不能单独作为删除的理由 |
## 规则没被遵守时
| 发现 | 怎么做 |
|---|---|
| 现场规则要求同源,但软链或导入缺了 | 在授权范围内补上,并确认平台实际加载到了 |
| 两份各自独立的规则文件内容不同 | 现场声明能唯一裁决就合并;否则列为待决 |
| 有能跑的代码却没有项目规则文件 | 建一份最小的规则文件(五件事,尽量短);工作空间有模板就按模板 |
| ignore 规则缺了安全红线要求的项 | 在请求范围和授权内直接补,并检查有没有已经被跟踪的密钥文件 |
| 命名不合规、根目录乱放文件 | 报告影响;移动、改名、删除通常列为待决 |
| 规则引用了已经退役的路径或命令 | 在当前机器上能确认、又不涉及别的设备时清掉;否则报告 |
| 同一种违规反复出现 | 用检查、hook 或测试固定下来;要不要自动实现,看现场授权 |
## 什么时候要查别的项目
下面任何一条成立,就去找实际依赖这个项目的下游,不要只改当前项目:
- 共享的接口、SDK、域名、认证、数据结构或环境变量变了;
- 部署或 CDN 这一层改变了下游能看到的行为;
- 公用的 Skill、脚本或模板被多个项目引用;
- 当前项目的文档明确列出了依赖方。
发现了下游,不等于获准去改它。先说明依赖的证据和影响,再按任务和工作空间的规则行动。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |