Codex Hardness Engineering Practice

codex-hardness-engineering-practice，简称 CHEP，是一份面向 Codex / Agent 工作流的工程化治理资产仓库。

它不是某个业务系统，而是从真实 D:\.codex 工作区中抽取、整理并公开的一组高复用资产，重点覆盖：

• AGENTS.md 设计与瘦身
• memory-first 知识路由
• Hook / pre-commit / CI 质量门禁
• 文档索引与模板体系
• 用户自建 skill 的沉淀方式
• 对公开仓库的敏感信息拦截

本仓库适合以下场景：

• 想给自己的 Codex / Agent 工作区建立一套可追溯、可审计、可扩展的工程规范
• 想把“提醒式规则”升级为 Hook、模板、文档索引和 CI
• 想参考一套真实可运行的 AGENTS + docs + hooks + skills 组合结构
• 想在公开仓库里降低 token、凭证、私钥误提交风险

设计目标

本仓库的核心目标不是“写一份长规范”，而是把规范变成可执行系统：

• 入口最小化：主 AGENTS.md 只保留高频、硬约束和路由
• 渐进式加载：优先入口页，再按任务类型加载专题文档
• 工具优先：能落到 Hook、Linter、CI 的规则，不只停留在文档
• 结果可审计：关键决策、检查结果和交付动作都能追溯
• 默认中文：沟通、文档、注释和模板均以中文为主

仓库内容

当前首批公开内容包括：

• AGENTS.md
• docs
• hooks
• scripts
• rules
• tests
• skills/user
• .pre-commit-config.yaml
• .github/workflows/agents-governance.yml

重点能力：

• 以 AGENTS.md -> docs -> hooks -> tests -> skills 的链路组织治理资产
• 通过 hooks/run_relevant_hooks.py 做“按改动路由最小必要检查”
• 使用 docs/process、docs/project-agents、docs/templates 组织工作流与模板入口
• 通过 hooks/audit_public_repo_secrets.py 拦截高风险凭证与敏感文件名

有意不公开的内容

为了避免把本地状态和敏感信息带进公开仓库，这个仓库刻意排除了以下内容：

• config.toml、auth.json、cap_sid
• .serena/、evidence/、memories/、plugins/
• 日志、缓存、sqlite、session、sandbox 运行时产物
• 历史状态文件、用户本地会话索引和任何真实 token

仓库根目录的 .gitignore 与 hooks/audit_public_repo_secrets.py 共同承担第一道防线；GitHub Actions 与 pre-commit 负责第二道防线。

目录结构

.
├─ AGENTS.md
├─ docs/
│  ├─ agent-style/
│  ├─ constraints/
│  ├─ mcp/
│  ├─ process/
│  ├─ project-agents/
│  ├─ skills/
│  └─ templates/
├─ hooks/
├─ rules/
├─ scripts/
├─ skills/
│  └─ user/
└─ tests/

快速开始

1. 克隆仓库

git clone https://github.com/cunyu277/codex-hardness-engineering-practice.git
cd codex-hardness-engineering-practice

2. 准备依赖

建议使用 Python 3.11+。

python -m pip install pre-commit ruff

3. 安装本地门禁

python hooks/bootstrap_precommit.py

4. 执行最小验证

python hooks/run_relevant_hooks.py --changed-only
pre-commit run --all-files
python -m unittest

路径约定与移植说明

这批资产源自真实的 D:\.codex 工作区，因此部分文档、模板或 skill 中仍会保留 D:\.codex 作为“规范路径示例”。

这不代表你必须把仓库克隆到这个路径；它只是在表达“这些资产原本位于 Codex 全局目录”。

如果你打算迁移到自己的环境，建议：

1. 保留仓库结构不变。
2. 将文档中的 D:\.codex 视为你的 Codex Home 占位符。
3. 按你的操作系统和解释器路径，调整个别脚本中的本地命令示例。

安全策略

本仓库默认采用“忽略 + 审计 + CI”三层拦截：

1. .gitignore 排除本地状态、凭证文件和运行时目录。
2. pre-commit 通过 hooks/audit_public_repo_secrets.py 审计高风险 token 与私钥标记。
3. GitHub Actions 在 push / pull request 时再次执行 pre-commit 与单元测试。

如果你准备在此基础上继续公开发布，建议额外开启：

1. GitHub Secret Scanning。
2. Branch protection。
3. 受保护分支的必过检查。

推荐阅读顺序

如果你第一次阅读这个仓库，建议按下面顺序进入：

1. AGENTS.md
2. docs/process/04-workflow-type-routing.md
3. docs/project-agents/00-index.md
4. docs/templates/00-index.md
5. hooks/README.md
6. skills/user/discover-locate-confirm/SKILL.md

适合二次演化的方向

如果你想把这套实践继续推到更强的工程化层级，优先考虑：

1. 增加独立的 secret scanning workflow，并接入 PR 必过检查。
2. 把路径示例进一步参数化，减少 D:\.codex 这种源环境路径对外部使用者的理解负担。
3. 将部分治理流程抽象成更通用的独立 Python 包或模板生成器，而不是只保留仓库内脚本。

许可证

本仓库采用 MIT License。