dotfiles

个人 macOS 开发环境。所有内容均通过符号链接就位；在此处编辑文件即为实时编辑。

它是什么

一个仓库掌控整台机器：shell、终端、编辑器、多路复用器，以及叠加在其上的 AI-agent 层。install.sh 为新 Mac 进行引导——Homebrew、软件包、字体、符号链接、nvm——之后恢复任何配置只需重新运行它。深色 yugen 主题按工具应用，并手动保持同步。

演变最多的部分是 [agents/：一套在 Claude Code、Cursor 和 opencode 之间共享的技能，通过一条有文档记录的流水线——头脑风暴、决策、规划、实现——将模糊的想法转化为已发布的 PR。

预览

编辑器 — 使用 lazy.nvim 的 Neovim

仪表盘

文件查找器

诊断

安装

git clone https://github.com/vmarcosp/dotfiles ~/projects/dotfiles
cd ~/projects/dotfiles && ./install.sh

该脚本是幂等的。它会安装 Homebrew（formulae 和 casks）、Nerd Fonts、oh-my-zsh 和 nvm，然后将所有配置符号链接到其系统位置。随时可以再次运行以恢复链接或获取新软件包。

内容概览

目录	内容	链接到
`env/`	`.zshrc`（oh-my-zsh、nvm、aliases）和 `.gitconfig`	`~/.zshrc`、`~/.gitconfig`
`nvim/`	Neovim 配置、lazy.nvim	`~/.config/nvim`
`kitty/`	Kitty 终端 + `yugen` 主题	`~/.config/kitty/`
`tmux/`	极简 tmux 配置	`~/.tmux.conf`
`better-tmux/`	TypeScript/React tmux 状态栏	`~/.config/better-tmux`
`bin/`	实用脚本（`notification`、`worktree`）	`~/bin/`
`agents/`	AI 技能和规则，跨工具共享	`~/.agents`、`~/.claude/*`、`~/.cursor/skills`
`claude/`	全局 Claude Code 设置	`~/.claude/settings.json`
`opencode/`	Opencode 配置、插件、主题	`~/.opencode/plugins`
`cursor/`	Cursor hooks 和 MCP servers	—
`wallpapers/`	桌面壁纸	—

install.sh 是完整符号链接映射的权威来源。

技能

技能位于 agents/skills/，并被符号链接到我使用的每个代理（Claude Code、Cursor、opencode），因此一次编辑即可在所有地方更新。它们沿一个维度划分——谁可以调用它们。用户调用 的技能仅在我输入时触发；它们编排一个流程。模型调用 的技能是代理在任务匹配时自行使用的。

流水线

核心技能构成了从模糊想法到已发布 PR 的流水线。每个技能都会生成一个文档供下一个技能消费，因此上下文可以跨会话和代理保留：

                       fuzzy idea
                           │
                     ┌─────▼──────┐
                     │ /brainstorm │  explore, stress, converge
                     └─────┬──────┘
             ┌─────────────┼─────────────┐
             ▼             ▼             ▼
        ┌────────┐    ┌────────┐    ┌────────┐
        │  /prd  │───▶│  /tdd  │    │  /adr  │
        │ the    │    │ the    │◀───│ binding│
        │ WHAT   │    │ HOW    │    │ record │
        └────┬───┘    └────┬───┘    └────┬───┘
             └──────┬──────┘─────────────┘
                    ▼
          fits in a single change?
          │ no                │ yes
    ┌─────▼─────┐             │
    │ /phasing  │             │
    │ roadmap,  │             │
    │ N phases  │             │
    └─────┬─────┘             │
          │ per phase         │
    ┌─────▼─────┐             │
    │   /spec   │◀────────────┘
    └─────┬─────┘
          ▼
    ┌───────────┐
    │/implement │  1 step = 1 verify = 1 commit → PR
    └─────┬─────┘
          ▼
  carry-over ──▶ /phasing (sync) absorbs and replans

brainstorm — 针对模糊想法的长篇会话，而非文档生成器。将每项主张都锚定在会话期间阅读的来源上，在批评前先进行钢人论证，通过测量而非估算来验证，并收敛为带有明确代价的权衡。退出时移交至 /prd、/tdd 或 /adr。
prd — 撰写产品需求：目标用户是谁、他们能做什么、每个场景下“完成”的标准是什么。仅描述行为——机制被禁止出现在文档中。输入可以是 brainstorm 产物、TDD 或普通描述。
tdd — 撰写技术设计：系统如何组合在一起，现状（As-Is）或目标状态（To-Be），并附带 mermaid 图表。陈述设计并链接支撑该设计的决策，而非重新论证这些决策。（该名称故意与测试驱动开发冲突——它永远不会自行触发。）
adr — 记录一项已做出的决策——背景、决策、后果。ADR 对下游具有约束力：/spec 和 /implement 将其视为契约，而非建议。
phasing — 将已确定的范围划分为阶段，每个阶段的规模恰好对应一个 /spec。构建依赖图，计算关键路径，并渲染并行工作流。每个阶段的 /implement 会留下一个遗留片段；同步运行会吸收这些片段并重新规划。
spec — 将一项变更转化为实施计划：基于实际读取的文件进行侦察，制定符合所有 ADR 的方案，以及按顺序排列的步骤，每个步骤都以可运行的 Verify 结束。那些超越变更本身的决策会被提升为 ADR，而不是在计划中消亡。
implement — 执行计划：一次一步，验证，提交，下一步。没有任何事情因为看起来完成了就算完成——只有当它的 Verify 运行并通过时才算完成。交付 PR，并且当计划是路线图阶段时，编写遗留事项并切换阶段状态。

实用工具

独立技能，未附加任何流水线。

用户调用

worktree — 根据分支名称创建或移除 git worktree，自动复制 .env 文件并安装依赖项。
review — 根据契约审查已交付的变更——包括 /spec 计划、路线图阶段的边界、约束性 ADR 以及测试的真实性——并返回包含阻塞性发现和建议性发现的裁决。

模型调用

notification — 当自主流程需要我介入时（如待处理的问题、人工关卡、失败），触发原生 macOS 通知。点击它可聚焦终端。
context7-mcp — 通过 Context7 路由库和框架问题以获取最新文档，而非过时的训练数据。

第三方 / 已安装

我从其他地方安装的技能；非我所有。

writing-great-skills — Matt Pocock 关于如何良好编写和编辑技能的参考。
todoist-cli — Doist 用于通过 td CLI 管理 Todoist 的技能。
richview — VTEX 用于从提示词和引用文件生成丰富、自包含 HTML 产物的技能。

规则

agents/rules/ 包含每个代理始终加载的指导——何时使用 Context7，何时触发通知。本仓库的范围限定规则和技能位于 .agents/。

许可证

MIT