Skip to content

CLAUDE.md

Latest commit

 

History

History
259 lines (184 loc) · 7.5 KB

CLAUDE.md

File metadata and controls

259 lines (184 loc) · 7.5 KB
Raw

CLAUDE.md — Coding-Rules LLM Wiki 操作手册

本文件是 LLM 维护 Coding-Rules Wiki 的核心配置。 每次操作 Wiki 前，LLM 必须先阅读此文件和 wiki/index.md。

一、Wiki 使命

Coding-Rules 是一个由 LLM 自主维护的结构化知识库，服务于：

  • 企业级微服务开发规范（阿里/华为/Google 编码标准）
  • AI Agent 开发（测试 Agent、Agent 架构、评估方法）
  • 部署踩坑经验（Docker、代理、网络）
  • 行业最佳实践（LangChain/LangGraph/CrewAI 等框架）

核心目标：知识以复利方式积累，不消失在聊天记录里。

二、三层架构

Coding-Rules/
├── CLAUDE.md              ← 本文件，Schema 定义
├── raw/                   ← 原始资料（只读，LLM 不修改）
├── wiki/                  ← LLM 全权维护的知识层
│   ├── index.md           ← Wiki 目录
│   ├── log.md             ← 变更日志（时间线）
│   ├── concepts/          ← 概念页（方法论/规范）
│   ├── concepts/ai-agent/ ← AI Agent 系列概念
│   ├── concepts/testing-agent/ ← 测试 Agent
│   ├── concepts/agent-frameworks/ ← 主流框架
│   ├── concepts/agent-evaluation/ ← 评估方法
│   ├── entities/          ← 实体页（项目/工具/组件）
│   └── summaries/          ← 原始文档摘要
└── skills/
    └── coding-rules-wiki/  ← 维护辅助 SKILL

各层职责

层级 职责 规则
raw/ 事实来源 只读，LLM 只读取不修改
wiki/ 知识积累 LLM 全权维护
CLAUDE.md 操作规范 定义结构、命名、操作流程

三、五个核心操作

操作 何时触发 做什么
ingest 新资料加入 读取原始文档 → 分析关键概念 → 更新/新建 10-15 个 wiki 页面 → 记录日志
query 用户提问 读 index → 读相关页 → 综合回答 → 归档有价值输出
lint 定期（每季度） 检查矛盾、过时、孤儿页面、缺失链接
audit 收到人工反馈 处理反馈 → 修正页面 → 归档到 resolved
compile 结构性调整 拆分/合并/重建索引页

四、命名与格式规范

页面命名

类型 风格 示例
概念页 Title Case 名词短语 Docker Best Practices, Agent Architecture
实体页 专有名词 resume-rag-service, playwright-test-agent
子概念目录 snake_case ai-agent/, testing-agent/

Wikilink 格式

  • 始终使用 [[Page Title]]
  • 首次提及概念/实体时加链接
  • 同一页面最多链接两次
  • 链接目标必须是 wiki/ 下存在的页面

YAML Frontmatter

每个页面顶部必须有：

---
title: <Page Title>
type: concept | entity | summary
tags: [标签1, 标签2]
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: [原始文档1, 原始文档2]
---

页面长度

类型 目标字数 硬上限
概念页 400–1200 字 1200 字
实体页 200–500 字 500 字
摘要页 150–400 字 400 字

拆分原则

当概念页超过 1200 字时，必须拆分：

wiki/concepts/ai-agent/
├── index.md              # 定义 + 子页面列表
├── agent-architecture.md # 400-1200 字
├── reAct-pattern.md      # 400-1200 字
└── multi-agent.md        # 400-1200 字

五、页面结构

概念页结构

---
title: <Title>
type: concept
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: [slug1, slug2]
tags: [tag1, tag2]
---

# <Title>

<一句话定义或核心思想>

## What it is

<清晰解释概念，假设读者有技术背景但不熟悉此主题>

## Key Properties / Tradeoffs

<要点列表或短段落>

## Relationship to Other Concepts

- [[Related Concept A]] — 关系说明
- [[Related Concept B]] — 对比或联系

## Open Questions

<当前 Wiki 尚不清楚的问题，驱动未来 ingest>

## Sources

- [[summaries/source-slug]] — (日期) 一句话描述

实体页结构

---
title: <Name>
type: entity
entity_type: project | tool | component
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: [slug1]
tags: [tag1]
---

# <Name>

<一句话描述>

## Key Features / Known Issues

<实体在 Wiki 上下文中的主要特点或已知问题>

## Related Concepts

- [[Concept A]] — 连接

## Sources

- [[summaries/source-slug]]

六、敏感信息处理

  • 不写入：API Key、密码、内网地址
  • 使用占位符：${ENV_VAR}, <YOUR_KEY>, <REPLACE_WITH_ACTUAL>
  • 版本历史：记录在 wiki/log.md

七、当前文章列表

概念 (Concepts)

AI Agent 系列（新增 2026-05-17）

  • [[ai-agent/index]] — AI Agent 设计模式（核心理念/组件/工作流）
  • [[ai-agent/agent-architecture]] — Agent 架构（Planner/Executor/Verifier、ReAct、CoT、多 Agent 协作）
  • [[testing-agent/testing-agent]] — 测试 Agent 开发（Playwright、自然语言驱动、选择器策略）
  • [[agent-frameworks/agent-frameworks]] — 主流框架（LangChain/LangGraph/CrewAI/Dify/AutoGen）
  • [[agent-evaluation/agent-evaluation]] — Agent 评估方法（SWE-bench/USEbench、质量维度）

代码规范系列

  • [[alibaba-coding-standards]] — 阿里巴巴代码规范（命名/常量/异常/并发）
  • [[huawei-coding-standards]] — 华为代码规范（头文件/函数/变量/注释）
  • [[google-engineering-practices]] — Google 工程实践（Code Review/C++风格）
  • [[llm-wiki-pattern]] — LLM Wiki 设计模式（核心理念/三层架构/五操作）
  • [[llm-wiki-toolchain]] — LLM Wiki 工具生态（摄入/编译/检查/前端）
  • [[docker-best-practices]] — Docker 构建与代理最佳实践
  • [[microservices-architecture]] — DDD 分层架构设计
  • [[coding-standards]] — 企业级编码通用规范

实体 (Entities)

  • [[resume-rag-service]] — RAG 微服务项目
  • [[docker-proxy]] — Docker 代理配置实体
  • [[playwright-test-agent]] — AI Agent Testing Framework（新增）

摘要 (Summaries)

  • [[summaries/karpathy-llm-wiki-gist]] — Karpathy LLM Wiki 原版 Gist
  • [[summaries/runoob-ai-agent]] — 菜鸟教程 AI Agent 教程摘要（新增）
  • [[summaries/qa-multi-agent-systems]] — 多 Agent 系统 QA 方法论摘要（新增）
  • [[summaries/useagent-paper]] — USEagent 统一软件工程 Agent 摘要（新增）
  • [[summaries/niodebugger-paper]] — NIODebugger flaky test 修复 Agent 摘要（新增）

八、待研究问题

  • 补充 Playwright 高级用法（性能监控、trace viewer）
  • 添加 Appium 移动端测试 Agent 相关内容
  • 补充 CI/CD 集成（GitHub Actions/Jenkins）测试 Agent
  • 添加 API 测试框架（Postman/Bruno）与 Agent 结合
  • 补充视觉测试（截图对比）相关规范

九、工具链

  • Obsidian — 推荐 Wiki 前端，支持图谱视图、Dataview、Marp
  • qmd — 本地 Markdown 搜索（Wiki >100 页时接入）
  • kb-lint — Wiki 健康检查工具
  • git — Wiki 本身是 git 仓库，版本历史免费拥有

十、本 Schema 的演化

本文档会随着实践深入持续迭代。每次重大变更记录在 wiki/log.md 中。

更新原则：

  • 新增操作类型 → 在第三章补充
  • 新增格式规范 → 更新第四章
  • 新增工具链 → 更新第九章