ArcKit新手避坑清单8个最常见的安装与工作流错误及解决方案【免费下载链接】arc-kitThe Enterprise Architecture Governance Harness — strategy, architecture, delivery, and assurance using AI coding assistants项目地址: https://gitcode.com/GitHub_Trending/ar/arc-kitArcKit是一个面向企业架构治理Enterprise Architecture Governance的开源 AI 工作流工具包帮助新手和普通用户借助 AI 编程助手完成战略规划、架构文档、交付与合规审计。本文总结了8 个最常见的 ArcKit 安装与工作流错误并给出快速解决方案帮你在前 10 分钟内跑通第一个架构文档少走弯路。一、安装篇4 个高频错误1️⃣ Claude Code 版本过旧装插件后命令全部失灵ArcKit 的 Claude Code 插件要求Claude Code v2.1.234 及以上版本。新手最常犯的错是直接装插件结果命令报 400 错误、研究代理静默失效——其实是宿主版本不达标v2.1.221 才修复了effort: max命令在关闭思考模式下的 400 问题详见 README.md。✅ 解决方案装插件前先执行一次升级并确认版本claude install latest2️⃣ 装错了插件市场旧仓库名README 明确指出旧市场tractorjuice/arc-kit仅为兼容保留新安装应使用tractorjuice/arckit-claude市场见 README.md。用旧市场安装会导致插件不更新、缺少新命令。✅ 解决方案在 Claude Code 中执行/plugin marketplace add tractorjuice/arckit-claude然后从 Discover 标签页或 CLI 安装核心插件claude plugin install arckitarckit-claude。3️⃣ 跳过核心插件直接装行业/地区覆盖插件ArcKit 市场里有 17 个插件arckit核心 14 个社区覆盖插件如arckit-uae、arckit-fr、arckit-eu、arckit-uk-nhs等。所有覆盖插件都依赖核心arckit插件单装覆盖插件会因依赖不满足而报错。另外arckit-au-energy行业层还额外依赖arckit-au辖区层。✅ 解决方案核心与覆盖插件一起安装只装你需要的辖区按需精简还能控制 token 占用覆盖插件的取舍逻辑见 README.md# 核心 你需要的辖区 claude plugin install arckit arckit-uae4️⃣ 用 CLI 平台Codex/Copilot却没执行arckit init插件方式Claude Code无需初始化但GitHub Copilot / Codex / OpenCode / Vibe / Kimi等平台必须先用 CLI 脚手架生成 prompt 文件与技能目录否则会出现 command not found官方排障清单见 README.md# 安装 CLIpip 方式 pip install githttps://gitcode.com/GitHub_Trending/ar/arc-kit.git # 在目标项目目录生成 AI 提示文件 arckit init my-project --ai copilot 快速自检Copilot 用户检查.github/prompts/arckit-*.prompt.md是否存在Codex 用户检查.agents/skills/目录。若不存在说明 init 没跑成功。二、工作流篇4 个高频错误5️⃣ 上来就跑业务命令忘了先执行/arckit:init/arckit:init是整个工作流的入口它创建projects/根目录和000-global/全局治理目录原则、政策、外部引用文档。没有初始化后续命令找不到项目目录、无法生成文档 ID详见 docs/guides/init.md。✅ 解决方案标准起手顺序是三步走/arckit:init # 第 1 步建立目录骨架 /arckit:principles # 第 2 步建立组织级架构原则 /arckit:stakeholders # 第 3 步进入你的第一个项目6️⃣ 大文档命令报 32000 output token maximum 超限错误/arckit:requirements、/arckit:sobc、/arckit:data-model、/arckit:sow等命令会生成长文档容易撞穿 Claude 的32K 输出 token 上限完整说明见 README.md。✅ 解决方案两条路按订阅选Team/Enterprise 订阅提高上限export CLAUDE_CODE_MAX_OUTPUT_TOKENS64000所有订阅通用改用 Write 工具策略让 AI 直接把文件写入磁盘、只在对话中给你摘要写入文件不计入输出 token/arckit:requirements 但请用 Write 工具直接写入文件只给我摘要7️⃣ 升级时覆盖了自定义模板和 README新手升级时最爱犯的错是直接重跑 init结果自定义的README.md被覆盖默认模板本身升级会刷新但projects/数据和.arckit/templates-custom/自定义模板会保留机制详见 docs/guides/upgrading.md 和 docs/guides/customize.md。✅ 解决方案升级前备份 README升级后恢复自定义内容一律通过/arckit:customize复制到templates-custom/而不是直接改默认模板cp README.md README.md.bak arckit init --here --ai codex # 原地升级保留项目数据 mv README.md.bak README.md8️⃣ BYO-LLM 配置错误协议不匹配或模型太小想用自己的模型跑 ArcKit 时两个典型坑完整指南见 docs/guides/byo-llm.md协议错配Claude Code 只说 Anthropic Messages 协议不能直接指向普通的/v1/chat/completions端点必须用支持/v1/messages的服务vLLM、llama.cpp、LM Studio 等或干脆走 Codex CLI / OpenCode 这条 OpenAI 协议路线模型太小单条/arckit:requirements就会塞入数千 token 指令完整模板官方建议至少 30B 级、64k 上下文的模型。小模型会放弃模板、自由发挥产出在文档管控和质量检查门被静默判负。✅ 解决方案配置后用/status核对 API 端点再跑一条轻量命令如/arckit:search确认请求确实打到了你的本地服务器。三、一张表快速对照#错误现象根因一行修复1命令报 400 / 研究代理失效Claude Code 低于 v2.1.234claude install latest2插件不更新、缺新命令用了旧市场名改装tractorjuice/arckit-claude3覆盖插件安装失败缺核心插件依赖与arckit一起安装4command not foundCLI 平台未执行 initarckit init 项目 --ai 平台5找不到项目目录未跑/arckit:init先 init再 principles632K token 超限长文档命令提高上限或用 Write 工具策略7README/模板丢失未备份直接升级先备份用--here原地升级8自托管模型不可用协议错配/模型过小选对协议路线 30B 级模型四、总结正确姿势三步走装对宿主优先 Claude Code功能最全需 v2.1.234其他平台走 CLI arckit init跑通骨架/arckit:init→/arckit:principles→ 第一个业务命令升级有备份备份 README、自定义模板走templates-custom/、升级用--here。ArcKit 生成的都是DRAFT 状态的初稿文档供合格的专业人员审阅——把它当作 AI 起草引擎而非合规结论本身正是它被设计的方式。按这份避坑清单操作你的第一个架构治理项目可以在今天上线。 延伸阅读初始化指南 · 升级指南 · BYO-LLM 指南 · 模板定制指南 · 插件源码目录 plugins/arckit-claude/【免费下载链接】arc-kitThe Enterprise Architecture Governance Harness — strategy, architecture, delivery, and assurance using AI coding assistants项目地址: https://gitcode.com/GitHub_Trending/ar/arc-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ArcKit新手避坑清单：8个最常见的安装与工作流错误及解决方案
ArcKit新手避坑清单8个最常见的安装与工作流错误及解决方案【免费下载链接】arc-kitThe Enterprise Architecture Governance Harness — strategy, architecture, delivery, and assurance using AI coding assistants项目地址: https://gitcode.com/GitHub_Trending/ar/arc-kitArcKit是一个面向企业架构治理Enterprise Architecture Governance的开源 AI 工作流工具包帮助新手和普通用户借助 AI 编程助手完成战略规划、架构文档、交付与合规审计。本文总结了8 个最常见的 ArcKit 安装与工作流错误并给出快速解决方案帮你在前 10 分钟内跑通第一个架构文档少走弯路。一、安装篇4 个高频错误1️⃣ Claude Code 版本过旧装插件后命令全部失灵ArcKit 的 Claude Code 插件要求Claude Code v2.1.234 及以上版本。新手最常犯的错是直接装插件结果命令报 400 错误、研究代理静默失效——其实是宿主版本不达标v2.1.221 才修复了effort: max命令在关闭思考模式下的 400 问题详见 README.md。✅ 解决方案装插件前先执行一次升级并确认版本claude install latest2️⃣ 装错了插件市场旧仓库名README 明确指出旧市场tractorjuice/arc-kit仅为兼容保留新安装应使用tractorjuice/arckit-claude市场见 README.md。用旧市场安装会导致插件不更新、缺少新命令。✅ 解决方案在 Claude Code 中执行/plugin marketplace add tractorjuice/arckit-claude然后从 Discover 标签页或 CLI 安装核心插件claude plugin install arckitarckit-claude。3️⃣ 跳过核心插件直接装行业/地区覆盖插件ArcKit 市场里有 17 个插件arckit核心 14 个社区覆盖插件如arckit-uae、arckit-fr、arckit-eu、arckit-uk-nhs等。所有覆盖插件都依赖核心arckit插件单装覆盖插件会因依赖不满足而报错。另外arckit-au-energy行业层还额外依赖arckit-au辖区层。✅ 解决方案核心与覆盖插件一起安装只装你需要的辖区按需精简还能控制 token 占用覆盖插件的取舍逻辑见 README.md# 核心 你需要的辖区 claude plugin install arckit arckit-uae4️⃣ 用 CLI 平台Codex/Copilot却没执行arckit init插件方式Claude Code无需初始化但GitHub Copilot / Codex / OpenCode / Vibe / Kimi等平台必须先用 CLI 脚手架生成 prompt 文件与技能目录否则会出现 command not found官方排障清单见 README.md# 安装 CLIpip 方式 pip install githttps://gitcode.com/GitHub_Trending/ar/arc-kit.git # 在目标项目目录生成 AI 提示文件 arckit init my-project --ai copilot 快速自检Copilot 用户检查.github/prompts/arckit-*.prompt.md是否存在Codex 用户检查.agents/skills/目录。若不存在说明 init 没跑成功。二、工作流篇4 个高频错误5️⃣ 上来就跑业务命令忘了先执行/arckit:init/arckit:init是整个工作流的入口它创建projects/根目录和000-global/全局治理目录原则、政策、外部引用文档。没有初始化后续命令找不到项目目录、无法生成文档 ID详见 docs/guides/init.md。✅ 解决方案标准起手顺序是三步走/arckit:init # 第 1 步建立目录骨架 /arckit:principles # 第 2 步建立组织级架构原则 /arckit:stakeholders # 第 3 步进入你的第一个项目6️⃣ 大文档命令报 32000 output token maximum 超限错误/arckit:requirements、/arckit:sobc、/arckit:data-model、/arckit:sow等命令会生成长文档容易撞穿 Claude 的32K 输出 token 上限完整说明见 README.md。✅ 解决方案两条路按订阅选Team/Enterprise 订阅提高上限export CLAUDE_CODE_MAX_OUTPUT_TOKENS64000所有订阅通用改用 Write 工具策略让 AI 直接把文件写入磁盘、只在对话中给你摘要写入文件不计入输出 token/arckit:requirements 但请用 Write 工具直接写入文件只给我摘要7️⃣ 升级时覆盖了自定义模板和 README新手升级时最爱犯的错是直接重跑 init结果自定义的README.md被覆盖默认模板本身升级会刷新但projects/数据和.arckit/templates-custom/自定义模板会保留机制详见 docs/guides/upgrading.md 和 docs/guides/customize.md。✅ 解决方案升级前备份 README升级后恢复自定义内容一律通过/arckit:customize复制到templates-custom/而不是直接改默认模板cp README.md README.md.bak arckit init --here --ai codex # 原地升级保留项目数据 mv README.md.bak README.md8️⃣ BYO-LLM 配置错误协议不匹配或模型太小想用自己的模型跑 ArcKit 时两个典型坑完整指南见 docs/guides/byo-llm.md协议错配Claude Code 只说 Anthropic Messages 协议不能直接指向普通的/v1/chat/completions端点必须用支持/v1/messages的服务vLLM、llama.cpp、LM Studio 等或干脆走 Codex CLI / OpenCode 这条 OpenAI 协议路线模型太小单条/arckit:requirements就会塞入数千 token 指令完整模板官方建议至少 30B 级、64k 上下文的模型。小模型会放弃模板、自由发挥产出在文档管控和质量检查门被静默判负。✅ 解决方案配置后用/status核对 API 端点再跑一条轻量命令如/arckit:search确认请求确实打到了你的本地服务器。三、一张表快速对照#错误现象根因一行修复1命令报 400 / 研究代理失效Claude Code 低于 v2.1.234claude install latest2插件不更新、缺新命令用了旧市场名改装tractorjuice/arckit-claude3覆盖插件安装失败缺核心插件依赖与arckit一起安装4command not foundCLI 平台未执行 initarckit init 项目 --ai 平台5找不到项目目录未跑/arckit:init先 init再 principles632K token 超限长文档命令提高上限或用 Write 工具策略7README/模板丢失未备份直接升级先备份用--here原地升级8自托管模型不可用协议错配/模型过小选对协议路线 30B 级模型四、总结正确姿势三步走装对宿主优先 Claude Code功能最全需 v2.1.234其他平台走 CLI arckit init跑通骨架/arckit:init→/arckit:principles→ 第一个业务命令升级有备份备份 README、自定义模板走templates-custom/、升级用--here。ArcKit 生成的都是DRAFT 状态的初稿文档供合格的专业人员审阅——把它当作 AI 起草引擎而非合规结论本身正是它被设计的方式。按这份避坑清单操作你的第一个架构治理项目可以在今天上线。 延伸阅读初始化指南 · 升级指南 · BYO-LLM 指南 · 模板定制指南 · 插件源码目录 plugins/arckit-claude/【免费下载链接】arc-kitThe Enterprise Architecture Governance Harness — strategy, architecture, delivery, and assurance using AI coding assistants项目地址: https://gitcode.com/GitHub_Trending/ar/arc-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考