本文件约束本项目内的写作和站点修改。全局规则继续生效；本文件只补充博客项目特有的内容加工、文件格式和验证要求。
- 这是基于 Jekyll 4.4.1 和 Minima 的中文技术博客。
- 文章存放在
_posts/，文件名使用YYYY-MM-DD-english-slug.md。 - 站点使用
jekyll-feed、Giscus 和自定义 Mermaid 处理插件。 - GitHub Actions 使用 Ruby 3.4 执行
bundle exec jekyll build，并在每天北京时间 08:00 重新部署未来日期文章。 _site/、缓存目录和 IDE 文件不是文章交付物。
技术博客的任务不是保存完整工作记录，而是把作者的隐性经验加工成读者能够理解、代入和复用的内容。
写作前先明确：
- 这篇文章帮助哪类读者解决什么问题；
- 读者最可能在哪一步卡住或产生误判；
- 作者经过什么证据、失败或取舍才得到当前结论；
- 读完后能够带走什么判断方法或可执行做法。
优先写出一个清晰主张。不要为了覆盖所有相关知识，把一篇文章写成完整手册。
动笔前用一句话写出文章主张：希望读者读完后相信什么、改变什么判断，或者能够完成什么动作。案例、解释和章节都应服务于这句话；无法推进主张的内容应删除或移到其他文章。
- 从具体症状、失败、冲突或常见误区切入，让读者先认出问题，再介绍概念。
- 把「同行一看就懂」的经验拆开说明：当时看到什么、为什么容易判断错、后来如何验证、什么条件下结论不成立。
- 原始材料是素材，不是文章结构。不要按聊天记录、提交顺序或工作步骤机械复述。
- 优先使用真实案例、代码路径、命令输出、前后差异和量化结果。无法验证的数据不要写成事实。
- 区分通用原则与当前环境限制。机器、版本或项目特有结论必须说明适用范围。
- 保留必要的失败过程，但只保留能够解释判断变化的部分。流水账、重复尝试和无关日志应删除。
- 抽象观点必须落到检查动作。不要停在「保持警惕」「结合实际」「提高判断力」；继续说明先检查什么、依据什么继续、出现什么结果必须停止。
- 用第一人称提供经历和证据，不用第一人称代替论证。重点写清楚哪条新证据改变了原有判断。
- 开头优先呈现读者已经遇到的症状、冲突或误判。不要先铺陈行业背景、工具定义和宏观趋势。
- 在前几段给出核心判断，让读者尽早知道文章准备证明什么。反常识判断必须由后文的事实、案例或推理支撑，不能只作为吸引点击的口号。
- 观点型文章优先围绕判断标准推进。每个标准说明三件事：检查什么、为什么容易判断错、什么结果下可以继续或必须停止。
- 一个可执行的方法至少应说明输入、负责人或执行主体、使用的工具、第一步动作和完成标准。答不出这些问题时，应明确它仍是思路或假设，不写成可直接落地的方案。
- 对数字、案例、政策、性能和外部行为，优先追溯原始出处。找不到来源时，可以作为待验证线索，但不能写成已确认事实。
- 用改变前提的方式检验结论。预算、目标、平台、版本或约束变化后结论仍完全不变时，检查它是否只是通用套话；结论依赖特定条件时，把这些条件写出来。
- 为重要结论补充失效条件或反例。边界越清楚，结论越可信，不要把特定项目中的经验包装成普遍规律。
- 结尾留下可复用的判断原则、最小检查清单或明确的责任边界。不要重复全文摘要，也不要用「未来值得期待」一类空泛展望收尾。
根据内容选择结构，不固定套用同一个模板。
建议使用：读者痛点 → 常见误判 → 作者经历或转折 → 方法 → 适用边界 → 可复用结论。
建议使用：具体问题 → 表面解释 → 核心判断 → 判断标准 → 验证动作 → 失效条件 → 责任边界。
建议使用：现象 → 影响范围 → 排查证据 → 根因 → 最小修复 → 验证 → 避免复发。
建议使用：要回答的问题 → 关键调用路径或组件关系 → 设计取舍 → 失败边界 → 可迁移的工程经验。
建议使用：完成后的结果 → 前置条件 → 最短可运行步骤 → 原理解释 → 常见错误 → 验证方式。
结构服务于主张。章节只有在推进论证时才保留，不要为了显得完整而增加「背景」「优势」「未来展望」等空泛章节。
- 默认使用简体中文，准确、自然、克制。中文与英文、数字之间保留合理空格。
- 中文正文使用直角引号
「」。代码、路径、字段、URL 和原始引用保持原样。 - 技术博客允许自然使用第一人称，以说明真实经历、判断和取舍。
- 允许少量第二人称帮助读者代入，但不要连续说教、假设读者无知或使用营销式召唤。此规则覆盖通用中文写作 Skill 对第二人称的机械禁用。
- 专业术语首次出现时，用一句大众语言说明它实际解决什么问题。不要只做英文翻译。
- 一个段落承载一个主要信息点。长短句交替，避免整篇都是列表、定义和规章语气。
- 重要判断可以单独成段，普通解释保持两到四句一个段落。短句用于强调，不要把整篇文章切成一句一段的口播稿。
- 列表用于并列条件、步骤或比较；能够用两三句自然说明的内容不要强行列点。
- 标题优先表达问题、冲突、结果或反常识判断。可以用「现象 + 真正原因」「常见误判 + 修正方法」制造张力，但不能夸大收益或使用「终极」「颠覆」「必看」「最大漏洞」等无法证明的词。
- 避免宣传腔、假装深刻的抽象词、无信息量的总结和过多粗体。
- 代码应来自真实实现、最小复现或明确标注的示意代码。不要把未经运行的代码描述为可直接使用。
- 命令、版本、路径、性能数据和外部 API 行为应尽量现场验证；无法验证时明确说明。
- 引用外部资料时优先使用官方文档或源码，并提供链接。不要虚构来源。
- Mermaid 只用于调用关系、状态变化或架构层级等文字难以说明的关系。使用
mermaid代码围栏，保持节点文字简短。 - 不公开凭据、内部地址、个人数据或其他敏感信息。示例必须脱敏。
新文章至少包含：
---
layout: post
title: "文章标题"
date: YYYY-MM-DD HH:MM:SS +0800
categories: [分类]
tags: [标签一, 标签二]
---- 文件日期与
date的日期保持一致。 - Slug 使用小写英文和连字符，保持稳定、可读，不在 URL 中放中文。
categories和tags复用现有命名，避免同义标签重复。- 如果有意定时发布，可以使用未来时间；本地构建验证需加
--future。否则不要因为随手填写未来时刻导致文章被跳过。 - 修改现有文章时保留原 URL，除非用户明确要求重命名。
- 文章任务默认只修改对应的
_posts/*.md。不要顺手改主题、布局、依赖或站点配置。 - 站点功能任务才修改
_config.yml、_layouts/、_includes/、_plugins/、assets/或依赖文件。 - 保留工作区中无关的未跟踪和未提交内容，尤其是
.idea/、其他文章和本地缓存。 - 不自动把文章写入向量记忆，不自动提交、推送或发布；这些操作需要明确请求。
文章修改完成后按成本从低到高验证：
- 检查 Front Matter、代码围栏、占位符、标题层级和中英文排版；确认前三段已经呈现具体问题和核心判断，主要观点后有证据、例子或动作；
- 运行
git diff --check -- <article>； - 首选
bundle exec jekyll build，未来文章使用bundle exec jekyll build --future； - 检查生成页面存在，并搜索标题、关键段落、代码块或 Mermaid 输出；
- 涉及布局、样式或交互时，再进行浏览器视觉验证。
当前本机可能出现 Ruby/Bundler 安装版本与 gem specification 不一致的问题。若 bundle exec 因环境损坏失败：
- 先区分文章错误与 Ruby 环境错误；
- 不要为了单篇文章自动重装 Ruby、修改
Gemfile.lock或升级依赖； - 可以在不改项目文件的前提下，用本机已安装且与锁文件匹配的 gem 版本完成临时构建；
- 如果无法安全构建，至少完成 Front Matter、Markdown 和 diff 检查，并准确报告构建阻塞。
主题自身的 Sass 弃用警告属于已知环境噪声，除非本次任务涉及主题升级，否则不要扩展范围处理。
最终说明应包含：
- 修改或新增的文章路径；
- 文章主张和主要结构变化；
- 实际执行的验证及结果；
- 未验证项、环境阻塞和剩余风险；
- 是否提交或发布。