12 KiB

Raw Blame History

Repository Guidelines

本文件为 AI Agent 提供项目操作手册与约束清单，确保 Agent 行为可控、可复现。

1. Mission & Scope（目标与边界）

允许的操作

读取、修改顶层文档：README.md、AGENTS.md、CONTRIBUTING.md 等
读取、修改 documents/、prompts/、skills/、workflow/、config/、tools/、repo/ 下的文档与代码
执行 make lint、备份脚本、prompts-library 转换工具
新增/修改提示词、技能、文档
提交符合规范的 commit

禁止的操作

修改 .github/workflows/ 中的 CI 配置（除非任务明确要求）
删除或覆盖 repo/backups/gz/ 中的存档文件
修改 LICENSE、CODE_OF_CONDUCT.md
在代码中硬编码密钥、Token 或敏感凭证
未经确认的大范围重构

敏感区域（禁止自动修改）

.github/workflows/*.yml - CI/CD 配置
repo/backups/gz/ - 历史备份存档
.env* 文件（如存在）

2. Golden Path（推荐执行路径）

# 1. 拉取最新代码
git pull --rebase origin develop

# 2. 运行 lint 检查
make lint

# 3. 执行修改任务
# ...

# 4. 再次 lint 验证
make lint

# 5. 提交变更
git add -A
git commit -m "feat|fix|docs|chore: scope - summary"
git push origin develop

3. Must-Run Commands（必须执行的命令清单）

环境要求

Node.js 16+（用于 markdownlint-cli）
Python 3.8+（用于 prompts-library 工具）
Git

核心命令

命令	用途	前置条件
`make help`	列出所有 Make 目标	无
`make lint`	校验全仓库 Markdown	需安装 markdownlint-cli
`bash repo/backups/一键备份.sh`	创建完整项目备份	无
`python3 repo/backups/快速备份.py`	Python 版备份脚本	Python 3.8+
`cd repo/prompts-library && python3 main.py`	提示词格式转换	pandas, openpyxl, PyYAML

prompts-library 支持的转换模式

Excel → Docs：将 Excel 工作簿转换为 Markdown 文档目录
Docs → Excel：将 Markdown 文档目录还原为 Excel 工作簿
Docs → JSONL：将 Markdown 文档转换为 JSONL 格式
JSONL → Excel：将 JSONL 转换为 Excel
Excel(JSONL) → JSONL：将内部 JSONL 格式的 Excel 转换为 JSONL 文件

4. Code Change Rules（修改约束）

架构原则

保持根目录扁平，避免巨石文件
三层内容架构：documents/ (知识) → prompts/ (指令) → skills/ (能力)

模块边界

documents/ - 中文知识库（方法论/入门/实战/资源）
prompts/ - 提示词入口与云端索引
skills/ - 可复用技能库（每个子目录一个 Skill）
workflow/ - 可复用工作流模板（自动开发闭环等）
config/ - 工具与开发配置（例如 Codex CLI）
tools/ - 预留：自定义脚本/小工具（保持可替换、可审计）
repo/ - 外部工具与依赖（含 Git submodule）

依赖添加规则

新增工具或库时记录安装方式、最小版本与来源
外部依赖来源记录在 repo/ 目录下
引入第三方脚本需标明许可证与来源

禁止行为

禁止"顺手重构/大范围改动"除非任务明确要求
禁止删除现有测试用例（除非任务要求）
禁止在代码中硬编码敏感信息

5. Style & Quality（风格与质量标准）

格式化工具

Markdown：markdownlint-cli（通过 make lint 执行）
CI 自动检查：.github/workflows/ci.yml

命名约定

文档、注释、日志使用中文
代码符号统一英文且语义直白
文件名小写加中划线或下划线

缩进与排版

全仓保持空格缩进（2 或 4 空格不混用）
行宽控制在 120 列内

设计品味

优先消除分支与重复
函数单一职责且短小

6. Project Map（项目结构速览）

.
├── README.md                    # 项目主文档
├── AGENTS.md                    # AI Agent 行为准则（本文件）
├── Makefile                     # 自动化脚本
├── LICENSE                      # MIT 许可证
├── CODE_OF_CONDUCT.md           # 行为准则
├── CONTRIBUTING.md              # 贡献指南
├── .gitignore                   # Git 忽略规则
│
├── assets/                      # 外部资源（指向在线表格）
│   ├── README.md                # 远程表格索引（唯一真相源）
│   └── AGENTS.md                # assets/ 目录规则
│
├── config/                      # 工具与开发配置
│   └── .codex/                  # Codex CLI 配置（项目级）
│       ├── config.toml          # Codex CLI 配置文件
│       └── AGENTS.md            # Codex/Agent 指南（本目录）
│
├── .github/                     # GitHub 配置
│   ├── workflows/               # CI/CD 工作流
│   │   ├── ci.yml               # Markdown lint + link checker
│   │   ├── labeler.yml          # 自动标签
│   │   └── welcome.yml          # 欢迎新贡献者
│   ├── ISSUE_TEMPLATE/          # Issue 模板
│   ├── PULL_REQUEST_TEMPLATE.md # PR 模板
│   ├── SECURITY.md              # 安全政策
│   ├── FUNDING.yml              # 赞助配置
│   └── wiki/                    # GitHub Wiki 内容
│
├── documents/                   # 文档库
│   ├── 05-哲学与方法论/        # 最高思想纲领与方法论
│   ├── 00-基础指南/             # 核心原则与底层逻辑
│   ├── 01-入门指南/             # 从零开始教程
│   ├── 02-方法论/               # 具体工具与技巧
│   ├── 03-实战/                 # 项目实战案例
│   └── 04-资源/                 # 外部资源聚合
│
├── prompts/                     # 提示词库（指向云端表格）
│   └── README.md                # 在线表格链接
│
├── skills/                      # 技能库（扁平化，详见 skills/README.md）
│   ├── skills-skills/           # 元技能核心
│   ├── sop-generator/           # SOP 生成
│   ├── canvas-dev/              # Canvas白板驱动开发
│   ├── headless-cli/            # 无头模式 AI CLI
│   ├── postgresql/              # PostgreSQL 专家
│   ├── timescaledb/             # 时序数据库
│   ├── ccxt/                    # 交易所 API
│   ├── tmux-autopilot/          # tmux 自动化
│   └── ...                      # 更多技能
│
├── workflow/                    # 工作流模板
│   ├── auto-dev-loop/           # 自动开发循环
│   └── canvas-dev/              # Canvas白板驱动开发
│
├── repo/                        # 可执行代码与外部依赖镜像
│   ├── README.md                # 外部工具索引
│   ├── AGENTS.md                # repo/ 目录规则
│   ├── prompts-library/         # Excel ↔ Markdown 互转工具
│   ├── chat-vault/              # AI 聊天记录保存工具
│   ├── Skill_Seekers-development/ # Skills 制作器
│   ├── html-tools-main/         # HTML 工具集
│   ├── my-nvim/                 # Neovim 配置
│   ├── MCPlayerTransfer/        # MC 玩家迁移工具
│   ├── XHS-image-to-PDF-conversion/ # 小红书图片转 PDF
│   ├── backups/                 # 历史备份脚本快照
│   ├── .tmux/                   # oh-my-tmux (submodule)
│   ├── tmux/                    # tmux 源码 (submodule)
│   └── claude-official-skills/  # Claude 官方 skills (submodule)
│
├── tools/                       # 工具目录（预留）
│   └── .gitkeep                 # 保持空目录被 Git 追踪

关键入口文件

README.md - 项目主文档，面向人类开发者
AGENTS.md - AI Agent 操作手册（本文件）
repo/prompts-library/main.py - 提示词转换工具入口
repo/backups/一键备份.sh - 备份脚本入口
skills/tmux-autopilot/ - tmux 自动化操控技能（基于 oh-my-tmux，含 capture-pane/send-keys/蜂群巡检脚本）
skills/sop-generator/ - SOP 生成与规范化技能（输入资料/需求 -> 标准 SOP）

7. Common Pitfalls（常见坑与修复）

问题	原因	修复
`make lint` 失败	未安装 markdownlint-cli	`npm install -g markdownlint-cli`
prompts-library 报错	缺少 Python 依赖	`pip install pandas openpyxl PyYAML rich InquirerPy`
CI markdown-lint 失败	`.github/lint_config.json` 缺失	TODO：新增 `.github/lint_config.json` 或调整 `.github/workflows/ci.yml` 的 lint 命令（需任务明确授权）
CI link-checker 失败	文档中存在失效链接	检查并修复 Markdown 中的链接
备份脚本权限不足	Shell 脚本无执行权限	`chmod +x repo/backups/一键备份.sh`

8. PR / Commit Rules（提交与 CI 规则）

Commit 规范

遵循简化 Conventional Commits：

feat|fix|docs|chore|refactor|test: scope - summary

示例：

docs: prompts - add new coding prompt
feat: skills - add postgresql skill
fix: readme - correct broken link

PR 必填内容

变更摘要
动机或关联 Issue
测试与验证步骤

CI 触发条件

push 到 main 分支
pull_request 到 main 分支

CI 检查项

markdown-lint - Markdown 格式检查
link-checker - 链接有效性检查

提交前清单

运行 make lint 通过
更新对应文档
确认不携带临时文件或机密数据

9. Documentation Sync Rule（强制同步规则）

任何功能/命令/配置/目录/工作流变化必须同步更新：

README.md - 面向人类开发者
AGENTS.md - 面向 AI Agent（本文件）

不确定的内容用 TODO 标注，不允许猜测。

Claude 上下文（合并在本文件）

本节为 Claude 系列模型提供项目上下文。

Repository Overview

Vibe Coding CN 是一个通过与 AI 结对编程实现"将想法变为现实"的终极工作流程。项目核心资产是其丰富的 prompts 和 skills 库。

Key Commands

# 提示词库转换
cd repo/prompts-library && python3 main.py

# Lint 所有 Markdown 文件
make lint

# 创建完整项目备份
bash repo/backups/一键备份.sh

Architecture & Structure

Core Directories

prompts/: 提示词库（指向云端表格）
skills/: 扁平化技能库（详见 skills/README.md）
documents/: 知识库（05-哲学与方法论、00-基础指南、01-入门指南、02-方法论、03-实战、04-资源）
repo/prompts-library/: Excel ↔ Markdown 转换工具
repo/chat-vault/: AI 聊天记录保存工具
repo/backups/: 备份脚本与存档

Key Technical Details

Prompt Organization: 提示词使用 (row,col)_ 前缀进行分类
Conversion Tool: 使用 Python + pandas + openpyxl
Documentation Standard: 用户文档使用中文；代码/文件名使用英文
Skills: 每个技能有独立的 SKILL.md

Development Workflow

遵循现有的提示词和技能分类系统
使用 prompts-library 工具进行提示词更新
Markdown 修改后运行 make lint
重大重构前运行备份脚本

Gemini 上下文（合并在本文件）

项目概述

vibe-coding-cn 是一个通过与 AI 结对编程实现"将想法变为现实"的终极工作流程。强调"规划驱动"和"模块化"核心理念。

技术栈

核心语言: Python
CLI 交互: rich, InquirerPy
数据处理: pandas, openpyxl
配置管理: PyYAML
文档规范: markdownlint-cli
版本控制: Git
自动化: Makefile

文件结构

详见上方 Project Map 章节。

12 KiB Raw Blame History Unescape Escape