Skip to content

AGENTS.md

Latest commit

 

History

History
90 lines (63 loc) · 3.61 KB

AGENTS.md

File metadata and controls

90 lines (63 loc) · 3.61 KB

AGENTS.md

本文件为 AI 编码助手提供本项目的写作规范与行为约束。

项目概述

一个基于 Hugo 的技术博客，内容以 AI、Agent 等前沿技术的开发实践与学习笔记为主。

博客文章规范

语言与语气

  • 使用中文写作。
  • 语气通俗、直接、干练，像在对一个同行开发者聊天，避免说教感和营销腔。
  • 用「你」称呼读者，不用「大家」「咱们」等过度口语化表达。
  • 不要使用任何第一人称人设（如「大家好，我是小明」「明友」等），文章是中性技术博客，不绑定特定博主身份。
  • 开头可直接切入主题，不需要寒暄式自我介绍。
  • 结尾干净利落，不需要「点个赞」「下篇文章见」之类的互动引导语。

结构与排版

  • 使用清晰的 H2/H3 层级结构，每个大节内部可拆多个小节。
  • 适当使用列表（有序/无序）和表格来组织对比信息。
  • 每个大节之间保留逻辑递进关系，整体有「从基础到进阶」的叙事弧线。
  • 使用 --- 分隔大段落内的过渡，保持视觉节奏。

比喻与图解

  • 核心概念必须配有通俗的类比或比喻（如「LLM 是顾问，Agent 是项目经理」「MCP 是 USB-C」「Skills 是菜谱」）。
  • 不需要生成图片占位符，也不生成实际图片。

代码示例

  • 技术概念需要配代码示例时，使用带语言标识的 Markdown 代码块。
  • 代码示例要紧跟解释文字，不要独立成段后不加说明。

对比与表格

  • 概念之间的对比优先使用表格呈现，表头清晰，每列对齐。
  • 表格前有一句引导语，表格后不再赘述相同内容。

总结

  • 文末必须有总结，采用分点回顾的方式，覆盖全文所有核心论点。
  • 总结部分可以用「快速回顾一下全文脉络」作为引入。
  • 最后用几个要点提炼出全文核心信息。

Frontmatter

每篇文章开头必须有 Hugo frontmatter：

---
title: "中文标题"
date: YYYY-MM-DDTHH:MM:SS+08:00
draft: true
author: "northes"
description: "一句话描述"
tags: ["学习笔记", "标签2"]
---

title 规范：

  • 使用中文，点明核心技术名词。
  • 常用模式：「技术名词：比喻/描述」（如 Harness Engineering：给大模型套上缰绳）、「技术名词 + 的/之 + 主题」（如 RAG 的基本原理）、「语言/工具 + 动作」（如 Go 错误处理实践）。
  • 不使用纯英文标题，不使用「万字长文」「一文搞懂」等营销式定语。

description 规范：

  • 一句话解释文章核心内容、回答的关键问题、或覆盖的知识范围。

  • 常用模式：疑问句（如 为什么 Claude Code 不使用 RAG 而是直接使用 grep）、「从...到...」概括式（如 从 Prompt 到 Context 再到 Harness，AI 工程的重心已经换了三次）、直接概括（如 RAG 的基本原理）。

  • 不要写「简介简介」等占位符，不要写成文章第一段的复述。

  • draft 默认 true。

  • author 固定为 "northes"。

  • tags 必须以 "学习笔记" 开头，后跟领域标签（如 "Agent"、"Golang"、"AI" 等）。

变更与提交

  • 每次完成文章编写或修改后，不要自动提交 Git。由用户自行审阅后提交。
  • 如需生成 commit message，遵循以下格式：
<type>(<scope>): <subject>
  • <type> 为 feat / fix / docs / style / refactor / test / chore 之一。
  • <scope> 为变更范围（如文件名、模块名）。
  • <subject> 为祈使句式简短描述，不超过 72 字符，使用中文。