chore(context): 对齐 Claude 5 上下文工程规范 — 仓库上下文 + bundled skills#164
Conversation
…ineering rules - Add root CLAUDE.md: gotchas-only (py-test 6h hang, proto stubs, gate scope, channels duck-typing trap), pointing at CONTRIBUTING/pr-standards instead of restating them. - Track .claude/skills + settings.json (narrowed .gitignore) so the verify dev skill reaches every clone; transient state stays ignored. - Bundled skills: replace legacy dotted tool names with real wire names (read_file/run_shell/web_search/memory_write...) in frontmatter AND prose — bodies were instructing models to call tools that don't exist. - memory.md + note-taking.md: fix invented memory_write(key/value/tags) schema to the real content/tag/namespace one; resolve the 'cite your memory' vs 'do not mention recalling' contradiction. - deep-research.md: kb.search does not exist -> memory_search + session_search. - verification-before-completion.md: rewrite from Iron-Law moralizing (word bans, rationalisation tables) to judgment-based guidance. - document-generator.md: compress forbid-list into environment constraints; scope markdown rules to file content vs chat persona. - huashu-design: 2,177-char description (truncated mid-sentence in the skill catalog) -> short description + <=200-char when_to_use; capability inventory moved into the body. - persona/default_grantley.md + nuwa-skill: WebSearch -> web_search. - Sync stale top-level skills/ trio with bundled versions (web_search.md contradicted the bundled default backend). - Delete docs/dev/build-fast.md + 2026-05-15 rust-build plan (describe a Rust workspace that no longer exists); CONTRIBUTING package count 25->28; docs/README: mark PLAN_*/PROMPT_*/RESEARCH_* as point-in-time artifacts.
github-actions
Bot
added
codex:needs-review
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9520a5134a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| memory_write( | ||
| key="research.logical_replication.verdict", | ||
| value="Recommended for our workload because <one sentence>; main risk = <one sentence>.", | ||
| tags=["research", "postgres", "replication"] |
There was a problem hiding this comment.
When this skill persists a research result, the example now invokes memory_write but still supplies the obsolete key, value, and tags arguments. The runtime schema accepts only content, tag, and namespace with content required and additional properties disabled, so following this example either fails tool-call validation or returns content_required, losing the intended durable research note. Update the example to use the current argument names.
Useful? React with 👍 / 👎.
|
|
||
| - 测试:`uv run pytest <具体路径>`(不要裸 `pytest`,不要本地跑全量套件——太慢且无必要) | ||
| - Lint:`uv run ruff check .`、`uv run mypy python/packages/`、`uv run lint-imports` | ||
| - 前端:`pnpm -C ui {test,typecheck,lint}`;UI 产物部署 = `pnpm build` + rsync `ui/out` |
There was a problem hiding this comment.
When an agent follows this deployment instruction from the repository root, pnpm build cannot produce ui/out: the root package.json defines no build script, while the build script exists only in ui/package.json:6-9. The repository's other build instructions consequently use pnpm -C ui build; use that command here as well so the newly added context does not direct agents to a failing deployment step.
Useful? React with 👍 / 👎.
| - If the user says "forget that", write a correcting note stating the fact | ||
| no longer holds, and stop using the old one. |
There was a problem hiding this comment.
When a user asks the agent to forget a fact, this instruction tells it to call memory_write with a correction, but dispatch_memory_write creates a new MemoryDoc and the memory host's upsert inserts a new chunk with a new ID; it neither replaces nor deletes the original note. Both the original fact and the correction therefore remain searchable in later sessions, and the successful write can falsely imply that the deletion request was honored. Route this case through an actual delete operation or explicitly report that deletion is unavailable rather than persisting another note.
Useful? React with 👍 / 👎.
github-actions
Bot
added
codex:reviewed
Same Rule-1 (judgment over rigid rules) pass as
verification-before-completion: keep each skill's actual method and
opinions, drop the absolutist framing ("delete it and start over, no
exceptions", "that's rationalization") that overconstrains
Claude-5-generation models.
github-actions
Bot
added
codex:needs-rerun
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dc8bfde7c8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - Brave: create a key at https://brave.com/search/api/ (free tier ~2k | ||
| queries/mo), then | ||
| corlinman config set providers.brave.api_key '{ env = "BRAVE_API_KEY" }' | ||
| export `BRAVE_API_KEY`, and restart the gateway. |
There was a problem hiding this comment.
When a user follows this newly added optional-backend setup, neither providers.brave.api_key nor BRAVE_API_KEY affects the built-in web_search: corlinman_agent/web/search.py:9-14,124-132 selects only ddg or serpapi and reads only the CORLINMAN_WEB_SEARCH_* variables. The gateway therefore continues using DuckDuckGo after the advertised setup; remove these instructions or wire Brave into the backend selector.
Useful? React with 👍 / 👎.
| - 前端设计语言 = Eclipse Minimal v2:纯黑单色、tint 只染光、全仓禁 `backdrop-filter`、字重 ≤500、图标自绘 sprite(零 lucide),有 vitest 强制。 | ||
| - `audit/*.md` 是审计工作产物,默认不随功能 PR 提交。 | ||
| - `skills/` 顶层目录是产品 example 默认 profile 的 skills(不是 dev skills);产品种子 skills 在 `python/packages/corlinman-server/src/corlinman_server/bundled_skills/`,两处同名文件要保持同步。 | ||
| - 产品运行时工具名是 snake_case wire 名(`read_file`/`run_shell`/`web_search`);skill/persona 里写工具名一律用 wire 名,点号旧名仅由 `tool_aliases.py` 兜底。 |
There was a problem hiding this comment.
When a contributor follows this new blanket convention while editing a blackboard-enabled skill, it directs them to replace blackboard.read/blackboard.write with snake-case names even though those are the actual dotted wire names (subagent/blackboard.py:60-61 and the dispatch branches in agent_servicer.py:3524-3530). The alias canonicalization only makes allowlist comparisons match; it does not register blackboard_read as a callable tool. Document the blackboard exception so future context cleanup does not teach agents nonexistent calls.
Useful? React with 👍 / 👎.
|
|
||
| ## 已知坑 | ||
|
|
||
| - **CI `py-test` 会间歇性挂死到 6 小时上限**,`main` 上也会发生,与你的 diff 无关。处理方式:rerun 该 job,不要对着自己的改动 debug。 |
There was a problem hiding this comment.
In the checked .github/workflows/ci.yml:78-82, the py-test job has timeout-minutes: 30, so it cannot hang until a six-hour limit. This new context also states categorically that such a timeout is unrelated to the contributor's diff and should only be rerun, which can cause a reproducible 30-minute hang introduced by a change to be dismissed as infrastructure flakiness. Update this pit to the configured timeout and avoid treating every timeout as unrelated without comparison evidence.
Useful? React with 👍 / 👎.
github-actions
Bot
added
codex:reviewed
github-actions
Bot
added
the
status: ✅ merge-ready
1 participant
背景
按 The new rules of context engineering for Claude 5 generation models 全项目整改的第一个 PR(仓库开发上下文 + 产品 skill 语料)。完整审计与两 PR 拆分见本地
audit/CONTEXT_ENGINEERING_2026-07-26.md(审计产物不入库)。第二个 PR 单独修agent_servicer.py的基线提示可达性 bug。改动
仓库开发上下文
CLAUDE.md:只写"坑"(py-test 6h 挂死、proto stubs 必须提交、gate 绿≠全绿、channels duck-typing 陷阱),流程性内容指向 CONTRIBUTING/pr-standards,不复述。.gitignore收窄:track.claude/skills/(verify dev skill 此前对所有 clone 不可见)+.claude/settings.json;worktrees/notes/locks 继续忽略。docs/dev/build-fast.md(278 行描述已不存在的 Rust workspace)及其唯一引用方(过期 Rust 构建计划);docs/README 标注PLAN_*/PROMPT_*/RESEARCH_*为时点性产物;CONTRIBUTING 包数 25→28。bundled skills(规则 4「单一来源」/ 规则 1「判断代替硬规则」)
file.read→read_file等 17 个文件)。gating 早已由tool_aliases.py兜底,但正文一直在教模型发不存在的调用。memory.md/note-taking.md:虚构的memory_write(key/value/tags)参数改为真实content/tag/namespace;消解"要引用记忆来源" vs 运行时"不要提你在回忆"的矛盾。deep-research.md:kb.search不存在 →memory_search+session_search。verification-before-completion.md:96 行 Iron-Law 说教(禁用词表、rationalisation 反驳表)重写为 55 行判断式纪律。document-generator.md(always-on):❌ 禁令列表压缩为环境约束;markdown 规则限定"文件内容",与 persona 的聊天纯文本规则解耦。huashu-design:2177 字符单行 description(目录里 200 字符处截成半句)→ 短 description + ≤200 字符when_to_use;能力清单移入正文。default_grantley.md/nuwa-skill:WebSearch→web_search。skills/三个过期副本同步(web_search.md 与 bundled 版对默认搜索后端说法相互矛盾)。验证
uv run pytest:skill 渐进披露 / meta card / refresh / starter seeding 36 passed。后续(已列入审计文档)
4 个巨型 skill 拆分(需先确认产品 agent 对 references/ 的文件访问模型)、
render_document工具化解除 always-on、subagent 行为底线、docs/ 计划归档触发。