阿白叔andClaude Opus 4.7 eafd46a8ba feat: add .codex-plugin/plugin.json for Codex / Codex++ install
Codex CLI's /plugin add accepts arbitrary git URLs and installs into
~/.codex/plugins/cache, not just OpenAI's curated catalog. Modeled the
manifest on Superpowers' .codex-plugin/plugin.json (skills field points
at ./skills/, interface block for UI metadata).

Bump both .claude-plugin/{plugin,marketplace}.json from 0.1.0 to 0.2.0
to signal Codex support.

README updated:
- Three install paths now: Claude Code plugin / Codex plugin / external spec
- Codex section explains the "no SessionStart hook" caveat — agents need
  to invoke using-praxis manually on first turn (or get prompted by the
  user)

Codex / Cursor users without plugin support continue to fall back to
the AGENTS.md / skills/ direct-read path documented in the next section.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-26 10:06:17 +08:00
2026-05-20 09:02:21 +08:00

praxis

Simgreek 团队的 AI 协作开发约定。给 AI 看的——每个项目里 AI 开干前先读这里。

完整规则在 AGENTS.md(英文)。skill 库在 skills/。这份 README 是给人的入口说明。

praxis 是什么

源自希腊语 praxis(实践)。Simgreek 团队的"踩过坑就写下来"的总和,给 AI agent 用。

支持三种用法(按完整度排序):

  • 作为 Claude Code 插件 —— /plugin install praxis 之后,session 一开 SessionStart hook 就把 using-praxis 强制注入 context,AI 行为受铁律约束。
  • 作为 Codex / Codex++ 插件 —— /plugin add <praxis-url> 装上,Codex 把 skills/ 里的 SKILL.md 注册成可调用的 skill。Codex 没有 SessionStart hook,但 skill 的 description 会让模型按需 invoke。
  • 作为外部规范—— 不装插件也能用:AI 进项目前读 AGENTS.md + 扫 skills/,靠提示词显式调用。Cursor / 其他工具走这条。

安装(Claude Code)

simgreek 仓库要求登录访问,所以 plugin URL 里要带个人 access token。每个团队成员一次性配一下。

第 1 步:在 Gitea 生成 token

登录 git.simgreek.com → 右上角头像 → Settings → Applications → 「Manage Access Tokens」 → 生成一个新 token:

  • Token 名字:claude-code-plugin(或你喜欢的)
  • 权限只勾 repository: read 就够,越小越好
  • 生成后立刻复制保存——离开页面就看不到了

第 2 步:在 Claude Code 装

把下面的 <YOUR_USERNAME> 和 <YOUR_TOKEN> 替换掉:

/plugin marketplace add https://<YOUR_USERNAME>:<YOUR_TOKEN>@git.simgreek.com/simgreek/praxis
/plugin install praxis

装完之后每次开新 session,praxis 的 SessionStart hook 会把 using-praxis 内容直接灌进 system context——AI 在做任何事之前都会读到铁律和 red flags。

升级:/plugin update praxis(自动用同一个 token 拉新版本)

卸载:/plugin uninstall praxis

安装(Codex / Codex++)

token 准备方式与 Claude Code 一致(上面第 1 步)。

在 Codex CLI 或 Codex++ 里:

/plugin add https://<YOUR_USERNAME>:<YOUR_TOKEN>@git.simgreek.com/simgreek/praxis

Codex 拉取仓库后会读 .codex-plugin/plugin.json,把 skills/ 下所有带 frontmatter 的 SKILL.md 注册成可调用 skill。需要时 AI 自己 invoke。

和 Claude 的差别:Codex 没有 SessionStart hook,所以 using-praxis 不会被强制注入。AI 进项目时,建议你第一句话说:

先读 using-praxis skill,了解我们团队的 SOP 再开始。

让 Codex 主动 invoke 一次,铁律就在 context 里了。后续任务正常用。

安全提醒(两边都适用):

  • token 会被工具写进本地配置——别让别人翻你电脑、别把 config 分享出去
  • token 不要提交进任何仓库
  • 共用电脑 / 临时机器装完用完,去 Gitea token 页面 revoke 掉
  • token 失效或换了,重新跑 install 命令用新 URL

不装插件怎么用

把这段提示词丢给 AI 当首句话:

请按以下顺序为本项目做初始化或推进任务:

1. 拉取并阅读 https://git.simgreek.com/simgreek/praxis 的最新内容
   (至少读 AGENTS.md 和 skills/using-praxis/SKILL.md,再扫 skills/
   下的其他 SKILL.md,匹配当前任务的读完)。

2. 读完后,如果是新项目初始化,问我以下信息(一次性问完):
   - 项目名 / 一句话定位
   - 技术栈(Node 版本、是否 Next.js / Express / 其他)
   - 远端仓库地址(gitee / git.simgreek.com / 其他)
   - 协作主分支名(main / dev)
   - 是否产品项目(要发分发渠道);是的话,分发渠道是什么
   - 需要哪些环境变量(只要变量名,不要值)

3. 拿到回答后,按 praxis 的规范:
   - git init(如果还没)+ 配 .gitignore(含 node_modules / .env*
     / 构建产物 / .claude/settings.local.json 等)
   - 落 .gitattributes(强制 LF,.bat/.cmd 用 CRLF,二进制标 binary)
   - 写 .env.example(仅变量名)
   - 写项目根 AGENTS.md,遵循 praxis AGENTS.md §2 的骨架,引用 praxis
     而不是复制规则
   - CLAUDE.md 写一行:@AGENTS.md
   - 写 README.md(中文,给人看,三段:是什么 / 怎么跑 / 怎么配 .env)

4. 全部建好后列出改动,等我确认再 commit。第一个 commit 不直接 push。

5. 整个过程严格遵守 praxis 的「AI 必须停下问人」规则——任务模糊、
   范围敏感、远端冲突、--force、上传分发渠道,这些必须停下来确认。

老项目补规范,把第 3 步换成"补齐缺失的文件,不要覆盖现有的内容;冲突先列出来问我"。

语言策略

  • 本 README 中文——给人读的入口
  • AGENTS.md / CLAUDE.md / skills/ 全英文——给 AI 读
  • commit、PR 标题、分支名、tag 注释全英文——AI 工具和搜索吃英文 metadata 更准

目录

praxis/
├── README.md             ← 中文入口(你正在看)
├── AGENTS.md             ← 全部团队规则(英文)
├── CLAUDE.md             ← 一行 @AGENTS.md import
├── .claude-plugin/       ← Claude Code 插件元数据
│   ├── marketplace.json
│   └── plugin.json
├── hooks/                ← SessionStart hook,强制注入 using-praxis
│   ├── hooks.json
│   ├── session-start
│   └── run-hook.cmd
└── skills/               ← AI 行为约束
    ├── using-praxis/     ← bootstrap:铁律 / red flags / 目录
    ├── git-upload/       ← 该传 / 不该传 / 泄密恢复
    ├── nodejs-project/   ← Node 项目 8 阶段执行 SOP(含编码检查)
    ├── debugging/        ← 4 阶段根因调查
    └── verification/     ← 完成前必须有证据

版本管理

本仓库按日期打 tag:YYYYMMDD(同一天多次发布加 -N 后缀)。tag 不可改、不可删、不可 force-push。

具体规则见 AGENTS.md §3 Git workflow。项目仓库自己用各自的 tag 方案(通常 semver vX.Y.Z),写在项目的 AGENTS.md 里。

Skill 怎么扩

碰到跨项目的具体话题、塞进 AGENTS.md 会拖肿(比如"PII 处理"、"eval 报告格式"),就在 skills/<topic>/ 下写 SKILL.md。

收录标准(同时满足):

  1. 至少踩过两次
  2. 比 AGENTS.md 通用规则窄
  3. 步骤稳定到能写下来

新加的 skill 要同时更新 AGENTS.md §5 Skills catalog 和 using-praxis/SKILL.md 的目录表。

远端

git.simgreek.com/simgreek/praxis · tags 列表

License

Internal.

S
Description
Team working agreements for AI-assisted development
Readme
157 KiB
0 Stars 8 Watchers 0 Forks
Languages
Shell 61.6%
Batchfile 38.4%