entapp-dev

一个 Claude Code 插件：在开发企业应用、持续迭代的过程中，保持

• 架构整洁 (clean architecture)
• 设计恰如其分 (appropriate design — 既不过度、也不不足)
• 代码整洁 (clean code)

技术栈无关——它约束的是结构关系与设计取舍，不绑定任何语言或框架。

规划：四个子 agent（开发流水线）

插件围绕一条开发流水线组织，每个阶段一个子 agent：

1. 需求 → 设计：理解需求，做概念分析建模，产出实现设计。
2. 设计 → 实现：参考设计编写 API Definition，编码实现，编写单元测试。
3. 测试 → 验收：编写并执行接口测试、功能验收测试。
4. Code Review：对实现做代码评审。

当前状态

• 进行中：agent 2 的 harness 相关文档。
• 已有基础知识资产（供各 agent 共享引用，是后续上下文的基础）：
  • knowledge/architecture/architecture.md — 基线架构标准（端口与适配器 / 六边形：层与环、依赖规则、层职责、请求流）。
  • knowledge/error-handling/error-handling.md — 通用企业应用错误处理指南（统一错误模型 + 传播机制：normalize / translate / wrap / expose，business vs technical，远程错误，重试）。
  • knowledge/logging/ — 日志规范（级别选择 + 多个示例）。
• 尚未开始：agent 4（Code Review）的工具与上下文文档——待 agent 2 完成后再做。

architecture.md 与 4 份 logging/*.md 各另存了一份 *.orig 原始快照，作为「防改坏」 的基线（这些文档尚未进入任何 commit，git 历史无法兜底，故保留快照）。*.orig 已 gitignore，仅存本地、不随插件发布。

标准如何进入会话（常驻 + 按需）

在已启用本插件的项目里，工程标准按两档进入会话上下文：

• 规则常驻：SessionStart 钩子（hooks/inject-harness.py）在每次会话开始 / resume / clear / compact 时，把三份「规则」文档逐字注入上下文（包在 <entapp-dev-harness>…</entapp-dev-harness> 标签内），全程常驻：
  • architecture.md、error-handling.md、logging-best-practices.md
  • 成本约 14k tokens / 会话（注入内容不改动原文）。
• 示例按需：冗长的 logging 示例文件不常驻，改由 logging-examples skill 在需要 写 / 评审日志代码时按需加载，指向 knowledge/logging/ 下的三份示例。

注：claude plugin details entapp-dev 显示的 always-on token 只统计了静态组件 （skill 描述等），不含钩子运行时注入的 additionalContext，因此会大幅低估常驻 成本。真实常驻成本以上面的 ~14k tokens 为准。

在其他项目中使用（按项目启用）

本插件按项目决定是否启用，不做全局自动生效。 在哪个项目的 .claude/ 设置里声明， 就只在那个项目生效；其余项目不受影响。

⚠️ 不要用 claude plugin install——那是 user scope（全局），会让每个项目的每个 会话都加载本插件。要全局禁用，删掉用户设置里的 enabledPlugins["entapp-dev@entapp-dev"]。

方式一：项目级启用——在目标项目里声明 marketplace 与启用项。两个键都要有：

• 只给自己用、且源是本机路径 → 写进 .claude/settings.local.json（个人、默认 gitignore）。
• 团队共享、源可被他人访问（git / GitHub）→ 写进 .claude/settings.json（提交入库）。

{
  "extraKnownMarketplaces": {
    "entapp-dev": {
      // 本机目录源（仅本机有效）：
      "source": { "source": "directory", "path": "/abs/path/to/entapp-dev" }
      // 团队共享改用 GitHub 源：
      // "source": { "source": "github", "repo": "<owner>/entapp-dev" }
    }
  },
  "enabledPlugins": { "entapp-dev@entapp-dev": true }
}

声明后，下一个会话起在该项目生效。要在某项目关掉，把该项目的 enabledPlugins["entapp-dev@entapp-dev"] 改为 false 或删除即可。

方式二：临时试用（不写设置、不安装）——在目标项目里：

claude --plugin-dir /abs/path/to/entapp-dev

⚠️ 缓存快照：改了 knowledge 文档不会即时生效。 经 marketplace / settings 安装后， 插件会被拷进 ~/.claude/plugins/cache/...，钩子读的是这份快照。你改完 knowledge/*.md 后，需 claude plugin update entapp-dev（或卸载重装）才会刷新； 否则下个会话注入的仍是旧内容。唯一例外是方式二 --plugin-dir，它直接读仓库活 文件，改完下个会话即生效——边迭代文档边验证时优先用它。

本仓库自身已通过 .claude/settings.local.json（个人、gitignored）启用，可在本项目 新开会话直接看到效果。

本地调试

# 在插件根目录（本仓库）加载本插件
claude --plugin-dir .

# 校验插件 / marketplace 清单
claude plugin validate .

# 单独验证钩子注入产物（应输出合法 JSON，含三份规则文档）
CLAUDE_PLUGIN_ROOT="$PWD" python3 hooks/inject-harness.py | python3 -m json.tool | head