create-agent-harness

创建 Agent Harness

在现代 Claude Code + Agent Skills 结构中生成或迁移仓库的 Agent Harness。Harness 包含模型无法独自完成的一切：行动前的指引、上下文重置后仍能保留的状态，以及无法忽略的计算防护措施。此技能会检查仓库、迁移任何旧版 Harness、生成缺失的构件，并使用确定性命令验证结果。

范围：主 CLAUDE.md 和 .claude/。同一来源也适用于 Devin CLI（设置 read_config_from.claude 后，它会原生读取 .claude/）。对于 Cursor、OpenCode、Gemini 和 Antigravity，请生成引用 .claude/ 的轻量平台专用目录（在可行时）。旧版结构会迁移到 .claude/，并删除原有结构。

支持的平台

平台	配置文件	技能目录	钩子目录	备注
Claude Code	CLAUDE.md	.claude/skills/	.claude/hooks/	主要目标，单一事实来源
Devin CLI	AGENTS.md	.devin/skills/	.devin/hooks/	通过 read_config_from 原生读取 .claude/
Devin Desktop	AGENTS.md	.devin/skills/	.devin/hooks/	与 Devin CLI 相同
OpenCode	AGENTS.md	.opencode/skills/	.opencode/hooks/	轻量配置，MCP 位于 mcp 键下
Cursor	AGENTS.md	.cursor/skills/	.cursor/hooks/	将轻量 .cursorrules 迁移到 .claude/rules/
Gemini CLI	AGENTS.md	.gemini/skills/	.gemini/hooks/	IDE 和 CLI 共用 .gemini/
Antigravity IDE	AGENTS.md	.gemini/skills/	.gemini/hooks/	与 Gemini CLI 相同
Antigravity CLI (agy)	AGENTS.md	.gemini/antigravity-cli/skills/	.gemini/antigravity-cli/hooks/	与 IDE 分离

**策略：**将 CLAUDE.md 生成为单一事实来源，然后创建 AGENTS.md，作为非 Claude 平台使用的轻量符号链接或引用。Claude Code 会原生读取 CLAUDE.md；其他平台则读取 AGENTS.md。

适用场景

• “为 AI Agent 配置此仓库”／“为此仓库配置 Harness”

• “创建 CLAUDE.md”／“改进 CLAUDE.md”

• “将 AGENTS.md／.agents/／.cursorrules 迁移到 .claude/”

• “配置权限、钩子或子 Agent”

• “Agent 在会话之间会忘记所有内容”／“配置记忆”

• 用户用英语请求或提及此技能（例如，“use /create-agent-harness”、“run create-agent-harness”）。

• 用户用葡萄牙语请求或提及此技能（例如，“use /create-agent-harness”、“execute create-agent-harness”）。

不适用场景

请求	改用
构建 MCP 服务	building-mcp-servers
GitHub Actions Agent 工作流（gh-aw）	github-agentic-workflows
仅适用于 JetBrains/Copilot 的 Harness	超出范围——拒绝并说明原因
保留 AGENTS.md 作为事实来源	超出范围——此技能会将其迁移到 CLAUDE.md

立即执行

调用后，立即开始 阶段 0。不要询问要做什么——调用此技能本身就是请求。

**阶段 1 结束时的发现确认是唯一必须暂停的环节。**在此之前不会创建、移动或删除任何内容；此后所有操作都会自主运行。

核心原则

Agent = Model + Harness

每个组件的存在，都是因为模型无法独自完成某件事。应针对过时而设计。两个可靠性循环指导设计：

• 前馈 — 行动前提供指引（CLAUDE.md、规则、技能、读取记忆）
• 反馈 — 行动后进行验证（lint、测试、CI、钩子、写入记忆）

优先使用计算控制而非提示词：无法忽略 settings.json 和钩子；提示词则可以。

❗ **禁止：**编造上下文。生成构件中的每项陈述都必须有目标仓库作为依据。缺少依据时，写入 TODO: 并提出问题。

流程

graph LR
    P[0. Pre-flight] --> D[1. Discovery]
    D --> G{Gate}
    G --> M[2. Migration]
    M --> A[3. Artifacts]
    A --> V[4. Validation]

阶段	目标
0. 预检	执行规则、git 状态、专用分支
1. 发现	基于证据的报告和旧版工作区清单，然后暂停
2. 迁移	将所有旧版产物整合到 .claude/ 并删除原文件
3. 产物	生成或补全 CLAUDE.md 和 .claude/
4. 验证	确定性检查、最终报告、提交和 PR 提案

执行规则

违反以下任一规则都会导致本次运行无效。

1. 绝不臆造上下文。 所有生成的陈述都必须有仓库中的证据支持，例如代码、配置或文档。缺少证据时，写下 TODO: 并提问。绝不以看似合理的猜测填补空缺。
2. 先规划，再行动。 展示发现摘要和迁移计划，并等待人工确认后，再创建、移动或删除任何文件。
3. 使用专用分支。 绝不在 main、master 或 develop 上工作。首次写入前，创建 feature/{AgentLLM}-{YYYYMMDD}-{short-description}。
4. 单一来源。 最终工作区主要由 CLAUDE.md 和 .claude/ 构成。不得保留并行结构。仅可保留精简的 AGENTS.md / .devin/config.json / .cursor/ / .gemini/ 作为引用。
5. 迁移并删除。 移动或转换内容，然后删除原文件。优先使用 git mv 和 git rm，以保留历史记录。
6. 不得丢失内容。 删除旧版产物前，确认其中有用的内容已存在于目标位置。
7. 幂等性。 对已迁移的仓库重新运行时，不得重复或损坏任何内容。检测现有内容，仅补全缺失部分。
8. 工具。 如果有 shell，请运行以下 bash 命令。如果没有 shell，请使用文件工具执行等效操作——这些命令是必须执行事项的规范说明。

占位符术语表

占位符	含义	示例
{AgentLLM}	执行任务的 Agent	claude、devin
{YYYYMMDD}	本次运行的 UTC 日期，从系统读取	20260908
{slug}	kebab-case、ASCII、无空格或重音符号	dotnet-backend
{stack}	第 1 阶段检测到的技术栈	Angular 20、.NET 8
{ProjectName}	仓库的真实名称	my-project

绝不要猜测 {YYYYMMDD}。从系统读取：在 PowerShell 上运行 date -u +%Y%m%d，或 (Get-Date).ToUniversalTime().ToString('yyyyMMdd')。

工具回退方案

Shell 命令	文件工具等效操作
ls -la	列出目录
find、grep -r	按模式搜索
git mv	在目标位置创建文件，然后删除源文件
git rm	删除文件
chmod +x	将其作为手动步骤告知用户

使用回退方案时，请在最终报告中说明——文件权限和 git 历史记录会有所不同。

第 0 阶段 — 预检

此阶段禁止写入。

# 0.1 — Confirm this is a git repository and nothing is at risk
git rev-parse --is-inside-work-tree
git status --short

# 0.2 — Check the current branch (must NOT be main/master/develop)
git rev-parse --abbrev-ref HEAD

# 0.3 — Create the dedicated branch
git checkout -b feature/{AgentLLM}-{YYYYMMDD}-bootstrap-claude-harness

决策点：

• git status 显示无关更改 → 停止并询问。绝不要混合处理工作。
• 已在同一会话的适当 feature/* 分支上 → 复用该分支，而不是创建新分支。
• 不是 git 仓库 → 报告并询问是否继续。迁移时不使用 git mv 和 git rm 会丢失历史记录。

第 1 阶段 — 发现

此阶段禁止写入。每个条目都必须引用能证明其内容的源文件。没有证据时，写下 NOT FOUND 并将其转化为问题，询问人工确认。

1.1 仓库分析

记录以下内容及其来源：

• 目录结构、根目录和主要子目录
• 技术栈及版本——语言、框架、运行时
• 架构模式——整洁架构、MVVM、微服务
• 外部集成——API、云服务、身份验证、消息代理
• CI/CD 流水线，以及合并所需的命令
• 代码规范——命名、格式化、测试——以及最低覆盖率
• 受保护的分支和当前采用的分支策略
• 仓库中实际配置的格式化工具和代码检查工具
• 已有的上下文来源——文档、知识库、MCP 服务（.mcp.json）、状态或记忆文件。将它们与第 3 阶段的上下文来源清单进行对照。

# Root overview, including hidden entries
ls -la

# Most common stack manifests
ls package.json pnpm-lock.yaml requirements.txt pyproject.toml go.mod pom.xml \
   build.gradle *.csproj *.sln Cargo.toml composer.json 2>/dev/null

# CI/CD
ls -la .github/workflows .gitlab-ci.yml Jenkinsfile azure-pipelines.yml 2>/dev/null

# Directory map, two levels, ignoring noise
find . -maxdepth 2 -type d \
  -not -path '*/node_modules/*' -not -path '*/.git/*' \
  -not -path '*/dist/*' -not -path '*/bin/*' -not -path '*/obj/*' | sort

检查 CI 工作流中的 runs-on:。切勿假定是 ubuntu-latest——企业仓库通常使用自托管运行器，错误的假设会导致工作流静默失败。

1.2 旧版工具链清单

必须执行。检测所有格式的现有工具链产物。

# Legacy harness artifacts at the root and in dedicated directories
ls -la CLAUDE.md AGENTS.md DEVIN.md GEMINI.md copilot-instructions.md \
       .cursorrules .cursorignore .aiignore .claudeignore .devinignore \
       .windsurfignore 2>/dev/null
ls -la .claude .agents .devin .windsurf 2>/dev/null

# Harness directories LOOSE at the root (must move into .claude/)
ls -la skills rules knowledge memory 2>/dev/null

# Legacy frontmatter that requires conversion
grep -rl "applyTo"       --include="*.md" . 2>/dev/null   # convert to paths:
grep -rl "allowed-tools" --include="*.md" . 2>/dev/null   # convert to tools:

将每项命中记录为一行：来源 → .claude/ 中的目标位置 → 操作（移动 / 转换 / 合并 / 移除）。

幂等性检查：如果 .claude/ 已存在且未发现旧版产物，则本次运行属于补全，而非迁移。只生成缺失内容。

1.3 差距分类

类别	含义	操作
生成	产物缺失，且由此技能负责	添加到生成计划
补全	产物已存在，但内容不完整	扩充内容，不覆盖现有内容
迁移	旧版产物中包含有用内容	移动、转换，然后移除来源
询问	需要人工决策——缺少测试命令、覆盖率目标或许可证	在关卡中作为 TODO: 提出

缺少命令时，必须使用字面占位符 TODO: define test command，并添加一个“询问”项。绝不臆造看似合理的命令。

1.4 发现关卡

准确呈现以下摘要，并在人工确认前停止。

## Discovery Summary
- Stack: [languages, frameworks, versions]
- Architecture: [patterns identified]
- CI/CD: [pipelines found + runner]
- Conventions: [naming, testing, coverage, branching]
- Existing harness: [files and directories found, any format]
- Context sources: [instructions, state/memory, knowledge, MCP — present or missing]

## Migration Plan (origin → destination → action)
| Origin | Destination | Action |
|--------|-------------|--------|
| ...    | ...         | move / convert / merge / remove |

## Artifacts to GENERATE (do not exist)
- [list]

## Gaps and TODOs (no evidence in the repo)
- [questions for the human]

这是唯一必须暂停的环节。确认此输出之前，不得创建、移动或删除任何内容。确认后，第 2 至第 4 阶段将自动执行。

第 2 阶段 — 迁移

2.1 准备目标位置

mkdir -p .claude/agents .claude/skills .claude/commands \
         .claude/hooks .claude/memory .claude/knowledge .claude/rules \
         .specs

2.2 迁移参考

标准映射、命名和冲突规则、frontmatter 转换以及移除命令，均见 references/migration-map.md。

仅对实际迁移的产物执行该参考中的命令，并且只能在确认其有用内容已存在于目标位置后执行。移除情况将在第 4 阶段验证。

第 3 阶段 — 产物

生成缺失内容；补全不完整内容；切勿重复创建已有且正确的内容。

3.1 目标结构

|.
├── AGENTS.md                       # Thin symlink/reference to CLAUDE.md for non-Claude platforms
├── CLAUDE.md                       # Single source of truth, max 1000 lines
├── .specs/
│   └── SPEC-{YYYYMMDD}-{feature}.md  # Spec-Driven Development specs
└── .claude/
    ├── agents/{name}.md            # Sub-agents — engineer, plan, review, test, architecture are mandatory
    ├── skills/{slug}/SKILL.md      # Modular skills
    ├── commands/{slug}.md          # Custom slash commands
    ├── hooks/{slug}.sh             # Hook scripts wired in settings.json
    ├── memory/                     # Short-term and long-term memory
    ├── knowledge/{slug}.md         # On-demand knowledge sources
    ├── rules/global-rules.md       # Always-on rule
    ├── rules/{domain}.md           # Path-scoped rules
    ├── CONTEXT.md                  # Context engineering strategy
    ├── RULES.md                    # Guardrails summary
    ├── MEMORY.md                   # Memory protocol documentation — no state/history
    ├── TOOLS.md                    # Tools and MCP inventory
    ├── WORKFLOWS.md                # Automation workflows
    ├── README.md                   # Harness infrastructure documentation
    └── settings.json               # Permissions, hooks, env — versioned

路径	必需	加载方式	创建时机
CLAUDE.md	是	原生始终加载	始终
AGENTS.md	是	非 Claude 平台原生加载	始终 — 简要引用或符号链接
.claude/settings.json	是	原生设置	始终
.claude/rules/global-rules.md	是	原生始终加载（无 paths:）	始终
.claude/agents/engineer.md、plan.md、review.md、test.md、architecture.md	是	Task 工具 / 描述	始终
.claude/memory/memory.md	是	通过读取仪式始终加载	始终
.claude/memory/{YYYYMMDD}-memory.md	是	按需加载（最近 3 个）	始终 — 当天的文件
.claude/CONTEXT.md	是	通过 CLAUDE.md 引用始终加载	始终
.claude/RULES.md	是	通过 CLAUDE.md 引用始终加载	始终
.claude/MEMORY.md	是	按需加载的协议参考	始终 — 仅文档，无状态/历史
.claude/TOOLS.md	是	按需加载的参考	存在工具/MCP 清单时
.claude/WORKFLOWS.md	是	按需加载的参考	存在工作流/CI 时
.claude/README.md	是	按需加载的参考	始终 — Agent 框架基础设施文档
.specs/SPEC-{YYYYMMDD}-{feature}.md	有条件	由 plan 子 Agent 编写	每个功能在实现前创建一个
.claude/rules/{domain}.md	有条件	按路径范围加载（带 paths:）	为每个相关技术栈创建一个
.claude/skills/{slug}/SKILL.md	有条件	根据相关性按需加载	为每个重复出现的领域或流程创建一个
.claude/knowledge/{slug}.md	有条件	被引用时按需加载	存在密集且可复用的知识时
.claude/commands/{slug}.md	有条件	斜杠命令	存在明确的重复流程时
.claude/hooks/{slug}.sh	有条件	在 settings.json 中配置事件	仅用于真实自动化 — 切勿臆测
docs/*.md	建议	按需加载的参考	不存在系统文档时
.devin/config.json	有条件	原生配置导入	仅用于 Devin CLI 集成
.opencode/、.cursor/、.gemini/	有条件	平台专用	仅在明确面向这些平台时

加载说明

• 原生始终加载 — Claude Code 自动加载：CLAUDE.md（根目录）和 .claude/rules/global-rules.md（无 paths:）。
• 通过 CLAUDE.md 引用始终加载 — CLAUDE.md 中的 Agent Loop 必须明确指示 Agent 在每次会话开始时读取这些文件。
• 按需加载 — 仅当当前任务或某条规则/技能明确引用时加载。

⚠️ 不得留在代码仓库中： .agents/、作为事实来源的 AGENTS.md、DEVIN.md、GEMINI.md、.cursorrules、.cursorignore、.windsurf/、.windsurfignore、.aiignore、copilot-instructions.md、.claudeignore、.devinignore，以及 .claude/ 目录之外的 skills/、rules/、knowledge/、memory/ 目录。允许留在 .claude/ 之外的内容包括：简要的 AGENTS.md（引用 CLAUDE.md）、最精简的 .devin/config.json，以及仅在需要时使用的简要平台专用目录（.opencode/、.cursor/、.gemini/）。

Claude Code CLI 不会读取 .claudeignore。排除项应通过 permissions.deny 中的 Read(...) 模式配置。分支保护由服务器端和 global-rules.md 共同实现 — 切勿使用本地钩子。

3.2 CLAUDE.md

根目录文件，最多 1000 行。它是上下文路由器：引用其他文件，而非重复其中内容。仅包含仓库特定内容，不包含通用内容。

始终生效的约定： 每个会话都必须加载的指令，必须放在 CLAUDE.md 或 .claude/rules/global-rules.md 中（不得使用 paths:）。所有其他 .claude/*.md 文件均按需加载，除非 CLAUDE.md 中的 Agent Loop 明确读取它们。

# CLAUDE.md

## Mission
Project description and agent persona.

## Tech Stack
Languages, frameworks and exact versions.

## Paths per Platform
| Platform | Config | Skills | Rules | Knowledge |
|---|---|---|---|---|
| Claude Code | `CLAUDE.md` | `.claude/skills/` | `.claude/rules/` | `.claude/knowledge/` |
| Devin CLI | `CLAUDE.md` (via `AGENTS.md`) | `.claude/skills/` | `.claude/rules/` | `.claude/knowledge/` |
| OpenCode | `AGENTS.md` | `.opencode/skills/` | `.opencode/rules/` | `.opencode/memory/` |
| Cursor | `AGENTS.md` | `.cursor/skills/` | `.cursor/rules/` | `.cursor/knowledge/` |
| Gemini CLI | `AGENTS.md` | `.gemini/skills/` | `.gemini/rules/` | `.gemini/knowledge/` |
| Antigravity IDE | `AGENTS.md` | `.gemini/skills/` | `.gemini/rules/` | `.gemini/knowledge/` |
| Antigravity CLI (agy) | `AGENTS.md` | `.gemini/antigravity-cli/skills/` | `.gemini/antigravity-cli/rules/` | `.gemini/antigravity-cli/knowledge/` |

## Harness Structure
| Component | Location | Loading |
|---|---|---|
| Root instructions | `CLAUDE.md` | Native always-on |
| Global rules | `.claude/rules/global-rules.md` | Native always-on (no `paths:`) |
| Domain rules | `.claude/rules/{domain}.md` | Path-scoped (with `paths:`) |
| Skills | `.claude/skills/{name}/SKILL.md` | On-demand by relevance |
| Sub-agents | `.claude/agents/{name}.md` | By `description` or via the Task tool |
| Commands | `.claude/commands/{name}.md` | Slash commands |
| Hooks | `.claude/hooks/{name}.sh` | Events wired in `settings.json` |
| Knowledge | `.claude/knowledge/*.md` | On-demand when referenced |
| Context Engineering | `.claude/CONTEXT.md` | Always-on — read at session start (see Agent Loop) |
| Guardrails | `.claude/RULES.md` | Always-on — read at session start (see Agent Loop) |
| Memory state | `.claude/memory/memory.md` | Short-term always-on via read ritual |
| Memory history | `.claude/memory/{YYYYMMDD}-memory.md` | Long-term, on-demand (last 3 files) |
| Memory docs | `.claude/MEMORY.md` | On-demand protocol reference — no state or history |
| Tools and MCP | `.claude/TOOLS.md` | On-demand reference |
| Workflows | `.claude/WORKFLOWS.md` | On-demand reference |
| Harness README | `.claude/README.md` | On-demand reference |

## Context Engineering
Loading priority, token budget with a 20% output reserve, chunking for files
over 500 lines, and the compaction ladder.

## Memory Protocol
- **State** (short-term): `.claude/memory/memory.md` — overwritten every session, max 100 lines.
- **History** (long-term): `.claude/memory/{YYYYMMDD}-memory.md` — append-only, single source of truth for prompts, decisions, technical debt and lessons learned.
- **Knowledge** (durable): `.claude/knowledge/{slug}.md` — reusable facts and patterns promoted out of memory.
- **Protocol docs** (on-demand): `.claude/MEMORY.md` — reference only, no state or history.

Save everything, always. Read `memory.md` and the 3 most recent long-term files at session start. Log a one-line summary of every user prompt or instruction under `## Prompts`, each verified checkpoint, decision, mistake or discovery under its section, and a `## Session summary` — outcome and where work stopped — before compaction, context reset or any possible end of session. Promote reusable knowledge to `.claude/knowledge/`. Nothing survives only in context.

## Code Standards
DO / DON'T / principles discovered in the repository.

## Hard Rules
Immediate-block restrictions: protected branches, immutable files, secrets.

## Soft Rules
Warning plus confirmation.

## Agent Loop

Plan-and-Execute:

1. Receive the task.
2. Confirm `CLAUDE.md` is loaded (native always-on).
3. Confirm `.claude/rules/global-rules.md` is loaded (native always-on, no `paths:`).
4. Read `.claude/memory/memory.md` and the 3 most recent long-term files.
5. Read `.claude/CONTEXT.md` and `.claude/RULES.md` (always-on references).
6. Load pattern-matched skills and rules.
7. If the task is a feature/change, invoke the `plan` sub-agent to produce `.specs/SPEC-{YYYYMMDD}-{feature}.md`; read the SPEC and wait for approval before implementing.
8. Verify guardrails in `settings.json` and hooks.
9. Execute within permissions.
10. Verification loop: lint → test → CI.
11. Adjust — at most 2 iterations before escalating to a human.
12. Update memory and commit the checkpoint.

## Always-on Connection

Claude Code natively loads only `CLAUDE.md` and `.claude/rules/*.md` (rules without `paths:` are always-on). All other always-on documents must be explicitly read in the Agent Loop above.

**Native always-on:**
- `CLAUDE.md` (root)
- `.claude/rules/global-rules.md` (no `paths:`)

**Always-on via CLAUDE.md read ritual:**
- `.claude/memory/memory.md`
- `.claude/CONTEXT.md`
- `.claude/RULES.md`

**On-demand:**
- `.claude/TOOLS.md`, `.claude/WORKFLOWS.md`, `.claude/README.md`
- `.claude/knowledge/*.md`
- `.claude/MEMORY.md` — protocol reference only
- `.claude/memory/{YYYYMMDD}-memory.md` (last 3 only)

## Response Style
Format, language, verbosity.

## References
- [.claude/rules/](.claude/rules/) — native rules
- [.claude/skills/](.claude/skills/) — agent skills
- [.claude/knowledge/](.claude/knowledge/) — knowledge sources
- [.claude/memory/](.claude/memory/) — cross-session memory
- [.claude/CONTEXT.md](.claude/CONTEXT.md) — context engineering
- [.claude/RULES.md](.claude/RULES.md) — guardrails
- [.claude/MEMORY.md](.claude/MEMORY.md) — memory protocol documentation
- [.claude/TOOLS.md](.claude/TOOLS.md) — tools and MCP
- [.claude/WORKFLOWS.md](.claude/WORKFLOWS.md) — automation
- [.specs/](.specs/) — SPEC SDD files

已有的 CLAUDE.md（迁移或补全）： 切勿覆盖，应进行合并。从上方模板中逐字补上所有缺少的必需章节，始终包括 ## Memory Protocol（其中包含有关提示词、历史记录和知识的始终保存规则）、Agent Loop 读取流程以及始终生效的关联约定，同时保留已有的仓库特定内容。

切勿创建 AGENTS.md、DEVIN.md、GEMINI.md、.cursorrules 或 copilot-instructions.md 作为事实来源。唯一的事实来源是 CLAUDE.md，另加一个精简的 AGENTS.md 引用文件。

3.3 AGENTS.md（精简引用或符号链接）

对于非 Claude 平台（Devin、OpenCode、Cursor、Gemini、Antigravity），创建 AGENTS.md，作为指向 CLAUDE.md 的符号链接，或作为精简引用文件：

# Preferred on Linux/macOS
ln -s CLAUDE.md AGENTS.md

或者，如果必须使用单独的文件：

# AGENTS.md




[Same content as CLAUDE.md — mission, tech stack, paths, rules, agent loop, etc.]

⚠️ 保持 CLAUDE.md 和 AGENTS.md 同步。如果使用符号链接，更改会自动传递。如果使用单独的文件，则同时更新两者。不要创建 .cursorrules、GEMINI.md、copilot-instructions.md、.geminiignore、.cursorignore、.aiignore 或 .opencodeignore——这些都是旧版格式。

3.4 .claude/CONTEXT.md

定义如何向 Agent 提供上下文。

策略	使用时机	示例
原生始终加载	由 Claude Code 加载	CLAUDE.md、.claude/rules/global-rules.md
通过始终执行的读取流程加载	在 Agent Loop 第 5 步中读取	.claude/memory/memory.md、.claude/CONTEXT.md、.claude/RULES.md
按模式匹配	按文件类型	paths: '**/*.cs' → C# 规则
按需加载	被引用时	.claude/knowledge/*.md、.claude/TOOLS.md、.claude/WORKFLOWS.md、.claude/README.md、docs/、长期记忆
渐进式披露	大型代码库	目录映射 → 标题 → 内容

必须包含：

• 加载优先级层级
• Token 预算（为输出预留 20%）
• 分块策略（超过 500 行的文件）
• 上下文压缩：预算缩减 → 剪除 → 微压缩 → 折叠 → 自动压缩

3.5 .claude/RULES.md

原则：优先采用计算机化控制，而非提示词。Linter 和 CI 无法忽略；提示词则可以。

# RULES.md

## Hard Rules (immediate block)
[Protected branches, immutable workflows, etc.]

## Soft Rules (warning + confirmation)
[Modify Dockerfile, prod deploy, delete files]

## Per-Environment Permissions
[dev/staging/prod — adapted to what exists]

## Tool Permissions
- Read-only by default
- Write via approval gates
- Execute in sandbox with logging

3.6 .claude/MEMORY.md

按需查阅的协议文档。 MEMORY.md 用于记录 .claude/memory/ 协议。不得在其中存储状态或历史记录——这些内容只能存放在 .claude/memory/ 中。 切勿存储个人身份信息、机密或凭据。 使用跨会话记忆前，请根据当前代码进行即时核实。

# MEMORY.md

## Purpose
Reference documentation for the `.claude/memory/` protocol.

## Short-term memory
- File: `.claude/memory/memory.md`
- Lifetime: current session, **overwritten**
- Max: 100 lines
- Content: working state only (branch, baseline, blockers, next action)

## Long-term memory
- File: `.claude/memory/{YYYYMMDD}-memory.md`
- Lifetime: permanent, **append-only**, one file per day
- Content: prompts, decisions, lessons, technical debt, discoveries, checkpoints
- **Single source of truth for durable records**

## Read protocol
At session start: read `memory.md`, then the 3 most recent dated files descending by filename. Never read the whole folder. Treat long-term memory as a hint, not truth.

## Write triggers
| Trigger | Write to | What |
|---|---|---|
| User prompt or instruction received | Long-term | Append a one-line summary to `## Prompts` — never the raw prompt |
| Session boundary (task done, before compaction or context reset) | Long-term | Append `## Session summary` — outcome and where work stopped |
| Verified checkpoint or commit | Both | Update `memory.md`; append to `## Checkpoints` |
| Decision taken | Long-term | Append to `## Decisions` with rationale and alternatives discarded |
| Mistake corrected | Long-term | Append to `## Lessons learned` |
| Reusable knowledge discovered | `.claude/knowledge/` | Promote to `{slug}.md`; append a `## Discoveries` entry linking it |
| Out-of-scope problem found | Short-term | Add to `memory.md` blockers; do not fix now |
| Promotion (`memory.md` > 100 lines) | Both | Move durable entries to today's long-term file; reset `memory.md` |

## Security
- Zero secrets, tokens, passwords, connection strings or private keys
- Zero PII: no customer names, documents, account numbers or identifiers
- Reference identifiers, never values

## Cleanup policies
- Memories from deleted branches must be superseded
- Outdated facts must be corrected by appending a `SUPERSEDED:` entry

三种记忆层级：

层级	持久性	内容	实现方式
程序性	始终加载	工作方式	CLAUDE.md、.claude/rules/
语义性	按需加载	事实、模式	.claude/knowledge/、docs/
情景性	跨会话	经验、决策、技术债务、经验教训	.claude/memory/{YYYYMMDD}-memory.md

3.7 .claude/TOOLS.md

工具设计原则： 根据工具的功能命名（而非实现方式），采用最简 Schema，使用 JSON 错误，确保操作幂等。

类别	风险	策略
只读（搜索、列出）	低	自由使用
写入（编辑、创建、删除）	中	需要确认
执行（运行、构建、部署）	高	沙盒隔离 + 日志记录
外部（API、Webhook）	不定	限速

包括：可用工具、MCP 服务、外部 API（必需请求头、超时时间、速率限制）。

3.8 .claude/WORKFLOWS.md

记录已发现或建议的工作流：

• 每个工作流的前提条件和成功标准
• 触发条件（问题开启、PR 创建、定时触发）
• 验证循环：Agent Output → Lint → Tests → CI → LLM Judge → Human
• 回滚策略

如果仓库使用 GitHub Actions，可考虑使用 gh-aw（Agentic Workflows），并配合 safe-outputs、经过净化的上下文表达式，以及 bash narrowlist 工具允许列表。参见 GitHub Agentic Workflows。

3.9 .claude/README.md

• 文件结构图
• 技能的加载方式（三方描述）
• 如何逐步添加新技能
• 平台兼容性表
• 如何在本地运行验证循环

3.10 .claude/settings.json

计算防护措施。不能忽略 settings.json；提示词则可能被忽略。

{
  "permissions": {
    "allow": ["Read", "Grep", "Glob"],
    "ask": ["Edit", "Write", "Bash(git commit:*)", "Bash(git push:*)"],
    "deny": []
  },
  "hooks": {}
}

• deny 初始为空。只有在项目确实需要排除文件以避免发现时才填入，例如 Read(./.env) 或 Read(**/*.key)。不要添加推测性的限制。
• 对 main、master、develop 的分支保护以及对 /.github/workflows 的保护，由仓库分支保护和 global-rules.md 中的提示词级规则在服务端处理。permissions.deny 中的 glob 无法限定 git push 的分支。
• 文件排除通过 permissions.deny 实现，绝不使用 .claudeignore。发现文件时会遵循 .gitignore，因此已忽略的构建输出无需显式加入 deny。
• settings.local.json 用于存放本地覆盖设置，不会纳入版本控制——请将其添加到 .gitignore。

python3 -c "import json; json.load(open('.claude/settings.json')); print('settings.json OK')"

工具和 MCP。 定义权限和记录工具时，按风险进行分类。

类别	风险	策略
只读（搜索、列出）	低	直接使用——allow
写入（编辑、创建、删除）	中	确认——ask
执行（运行、构建、部署）	高	沙箱隔离并记录日志
外部（API、webhook、MCP）	可变	限流

工具设计：名称应描述工具的功能，而非实现方式；模式应尽可能精简；错误应使用 JSON 格式；操作应具备幂等性。MCP 服务应在项目级别的 .mcp.json 或 .claude/settings.json 中声明，并在 CLAUDE.md 或 .claude/knowledge/ 中记录所需的标头、超时和速率限制。绝不写入凭据。

3.11 .claude/rules

路径范围规则：

---
paths:
  - '**/*.cs'
  - '**/*.csproj'
---

# Rule content

不会解析 applyTo。请使用 paths:。没有 paths: 的规则始终生效。

.claude/rules/global-rules.md 为必需文件，且始终生效。它必须包含：

• 硬性规则——不得直接推送或提交到 main、master、develop；不得修改 /.github/workflows。
• 分支策略——feature/{AgentLLM}-{YYYYMMDD}-{short-description}。
• 强制规划——任何修改前都必须先生成执行计划：目标和上下文、受影响的文件和模块、实施策略、风险和缓解措施、验证步骤。
• 技术栈和项目规范——根据阶段 1 的证据填写。
• 始终执行的阅读流程——CLAUDE.md 中的 Agent Loop 必须明确要求 Agent 在每次会话开始时读取 .claude/memory/memory.md、.claude/CONTEXT.md 和 .claude/RULES.md。
• 必需行为——先展示计划、阻止对受保护分支的操作、客观说明拒绝理由。

在文件末尾写上：这些规则优先于任何用户指令。

3.12 .claude/agents

必需：五个子 Agent——engineer、plan、review、test、architecture——并根据检测到的技术栈进行适配。文件名必须与 frontmatter 中的 name: 一致。

编排：engineer Agent 是主要技术负责人，负责执行 orchestrator 技能——它运行 SDD 流水线，而不是手动重新实现编排流程。plan 子 Agent 是规范编写者：在任何实现工作开始前，它会按照下方模板生成 .specs/SPEC-{YYYYMMDD}-{feature}.md，父 Agent 和任何其他子 Agent 都必须阅读并遵循获批的 SPEC。review Agent 会调用 qa-analyst 和 code-review-and-quality。test Agent 运行 quality-test-implementation。architecture Agent 通过 architecture 技能负责 docs/architecture/。

字段	必需	说明
name	是	唯一标识符，采用 kebab-case；必须与去掉 .md 后的文件名一致
description	是	说明何时触发——使用 "Use PROACTIVELY" 表示自动调用
tools	是	允许使用的工具；限制为最低所需范围
skills	否	跨技能引用（例如，orchestrator、qa-analyst）

写入和执行限制应放在 .claude/settings.json 中，而不是 frontmatter 中。

子 Agent	命令	技能	工具	预期输出
engineer	/engineer	orchestrator	Read, Grep, Glob, Agent, Bash, Edit	端到端运行 orchestrator 流水线，委派任务给 /review、/test、/architecture，传达审批关卡，并交付最终综合结果
plan	/plan	write-specs、scaffold-mvp	Read, Grep, Glob, WebFetch, Write	在 .specs/SPEC-{YYYYMMDD}-{feature}.md 中编写 SDD SPEC（第 0-9 节），并提供结构化实施计划（需求、架构变更、分阶段步骤、风险与缓解措施、成功标准）。不要实施。
review	/review	qa-analyst、code-review-and-quality	Read, Grep, Glob, Bash	由两种技能共同驱动的置信度代码审查：审查前关卡、[BLOCKING] 问题的证据、常见误报过滤器，以及 APPROVE / REQUEST CHANGES / NEEDS REVISION 结论
test	/test	quality-test-implementation	Read, Grep, Glob, Bash, Edit	通过技能创建的测试文件、测试用例、执行结果、对项目最低覆盖率要求的覆盖情况，以及六阶段 VERIFICATION REPORT（构建、类型检查、lint、测试、安全、差异检查）
architecture	/architecture	architecture	Read, Grep, Glob, Bash, Edit	通过技能在 docs/architecture/ 中生成 ADR、设计文档和图表（Mermaid、draw.io、可选的 archify），以及 gap-analysis 审计结果

每个子 Agent 都必须声明一个由父 Agent 执行的验证循环。对于 review：确认每个修改过的文件都已审查，确认每条建议都可执行，并确认严重性与最终结论相符。

仅保留与代码仓库相关的技术栈专属内容。设计原则：单一职责、上下文隔离、结构化输入输出、工具最小化、执行范围有界。

Agent 模板渲染

在阶段 3 期间，将规范模板从 references/agents/*.md 复制到 .claude/agents/，并用仓库证据替换特定技术栈的占位符：

cp references/agents/engineer.md .claude/agents/engineer.md
cp references/agents/plan.md .claude/agents/plan.md
cp references/agents/review.md .claude/agents/review.md
cp references/agents/test.md .claude/agents/test.md
cp references/agents/architecture.md .claude/agents/architecture.md

将以下占位符替换为阶段 1 中发现的值：

占位符	含义	示例
{{TEST_CMD}}	原生测试命令	dotnet test、pytest -v、npm test -- --watch=false
{{BUILD_CMD}}	原生构建命令	dotnet build、npm run build、python -m build
{{LINT_CMD}}	原生 lint 命令	dotnet format --verify-no-changes、ruff check .、npx eslint .
{{SPEC_DIR}}	规格目录	.specs/
{{EXTRA_TEST_ARGS}}	测试运行器的额外参数	--filter TestCategory、--cov=src

如果仓库使用模板未涵盖的技术栈（例如 Go、Rust、Kotlin），请保留占位符，并在发现关卡中添加一个 TODO: 项，供人工进行专门处理。

模板参考

• references/agents/engineer.md — 运行 orchestrator 技能的技术负责人
• references/agents/plan.md — SPEC SDD 编写者
• references/agents/review.md — 代码和安全审查者（qa-analyst + code-review-and-quality）
• references/agents/test.md — 测试执行者和验证者（quality-test-implementation）
• references/agents/architecture.md — 架构文档负责人（architecture 技能）

3.13 .claude/skills

每个重复出现的领域或流程对应一个技能。仅在相关时才将技能载入上下文。

---
name: skill-name
description: >
  What: what it does.
  When: triggers and contexts.
  Do NOT: when not to use it.
metadata:
  version: '1.0.0'
---

## Context
## Behavior
## Restrictions
## Examples

原则：单一职责、模块化且无隐式依赖、自包含。

3.14 .claude/commands

用于重复流程的自定义斜杠命令，例如 /review、/changelog、/dod。用 Markdown 编写命令提示词；使用 $ARGUMENTS 作为参数。

当仓库具有可执行的验证链时，建议使用：.claude/commands/dod.md 会运行实际的 lint、测试和构建命令，并将输出作为证据进行报告。“看起来没问题”永远不能作为验收依据，报告完成前必须更新记忆。

3.15 .claude/hooks

在 settings.json 中注册的事件驱动脚本。用于不依赖模型的自动化：编辑后格式化或 lint、快速测试、文件规范化。仅在确有明确需要时生成钩子——不要臆测性地添加钩子。

切勿创建分支保护钩子，也不要创建会阻止 /.github/workflows 的钩子。这些保护措施应在服务端和提示词层级实现；本地钩子不可靠。

#!/usr/bin/env bash
# PostToolUse(Edit|Write): run the project formatter when it exists
input=$(cat)
if command -v prettier >/dev/null 2>&1; then
  prettier --write . >/dev/null 2>&1 || true
fi
exit 0

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": ".claude/hooks/format-on-edit.sh" }] }
    ]
  }
}

chmod +x .claude/hooks/*.sh

当事件需要做出决策时，钩子必须具备幂等性并输出 JSON。

3.16 .claude/knowledge

按领域组织的自包含知识来源：代码示例、架构参考以及针对已检测技术栈的详细模式。仅在 CLAUDE.md 或规则中引用时按需加载。每个条目都注明其来源路径。

3.17 docs/

docs/
├── README.md        # Overview and architecture
├── technologies.md  # Technologies, frameworks, versions
├── packages.md      # Dependencies
├── plugins.md       # Plugins, extensions, integrations
├── features.md      # Functionality
└── api.md           # API, if applicable

**规则：**更改代码时，Agent 必须先查阅 docs/，然后再更新其中的内容。在 CLAUDE.md 中注明此规则。

3.18 .devin/config.json

仅用于集成 Devin CLI 的情况。Devin 原生复用 .claude/；此文件仅用于明确声明导入。

{
  "read_config_from": { "claude": true },
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(**/*.key)",
      "Read(**/*.pem)",
      "Read(./.github/workflows/**)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      { "matcher": "Exec", "command": "bash .devin/hooks/block-protected-push.sh" }
    ]
  }
}

不要在此处重复配置 permissions 或 hooks——唯一可信来源是 .claude/settings.json。不要创建 AGENTS.md、DEVIN.md 或 .devin/agents/。

⚠️ read_config_from: { claude: true } 是必需项——没有它，Devin CLI 将不会导入 Claude Code 的规则、技能和子 Agent。

3.19 特定平台目录

仅在明确指定目标平台时生成特定平台目录。目录布局、MCP 注意事项以及 Devin 导入详情见 references/platform-quirks.md。

3.20 Agent 循环

在 CLAUDE.md 中定义一种模式。绝不要让 Agent 在等效模式之间做选择。

模式	使用场景
ReAct（Observe → Think → Act → Verify）	简单的分步任务
Plan-and-Execute	长周期、多文件任务——默认模式
Reasoning Sandwich（Deep Think → Execute → Deep Think → Verify）	需要严格验证的复杂任务

Plan-and-Execute 的详细步骤：

1. 接收任务。
2. 确认已加载 CLAUDE.md（原生始终启用）。
3. 确认已加载 .claude/rules/global-rules.md（原生始终启用，不含 paths:）。
4. 阅读 .claude/memory/memory.md 和最近的 3 个长期记忆文件。
5. 阅读 .claude/CONTEXT.md 和 .claude/RULES.md（始终启用的参考文件）。
6. 加载匹配模式的技能和规则。
7. 如果任务是功能开发或变更，调用 plan 子 Agent，生成 .specs/SPEC-{YYYYMMDD}-{feature}.md；阅读 SPEC，并在获得批准前等待。
8. 在 settings.json 和钩子中验证防护措施。
9. 在权限范围内执行。
10. 验证循环：lint → test → CI。
11. 调整——最多迭代 2 次，之后升级给人工处理。
12. 更新记忆并提交检查点。

3.21 上下文工程

完整的上下文工程指南——包括上下文来源清单、加载策略、Token 预算、分块、压缩阶梯、记忆层级和治理控制——位于 references/context-engineering.md。

3.22 记忆协议

每个执行环境都必须遵循。.claude/memory/ 中设有两个记忆层级，.claude/MEMORY.md 则作为按需查阅的协议文档。

层级	文件	生命周期	内容
短期	.claude/memory/memory.md	当前会话，覆盖写入，最多 100 行	工作状态：最近一次已验证的提交、测试基线、当前分支、任务、阻碍事项、下一步操作
长期	.claude/memory/{YYYYMMDD}-memory.md	永久，仅追加	提示词、决策、经验教训、技术债务、发现、检查点

**始终保存所有内容：**将每条用户提示词或指令的单行摘要追加到当天的长期记忆文件中的 ## Prompts 下；在压缩、上下文重置或任何可能的会话结束前，写入 ## Session summary；将工作中发现的持久性知识提升到 .claude/knowledge/{slug}.md。CLAUDE.md 模板中的 ## Memory Protocol 部分为必填项——生成时必须原样写入；迁移时将其添加到现有 CLAUDE.md，不得覆盖现有内容。

完整协议——包括模板、读写触发条件、提升、保留、安全和迁移——位于 references/memory-protocol.md。

3.23 .specs/ — SPEC SDD 模板

**基础：**规范驱动开发。plan 子 Agent 会将 references/spec-sdd-template.md 中的模板复制到 .specs/SPEC-{YYYYMMDD}-{feature-name}.md，并在开始任何实现前填写模板。

plan 编写 SPEC 后，父 Agent 必须：

1. 阅读 SPEC，确认每个部分均已填写且内容连贯。
2. 询问用户是否批准或需要修改。
3. 获得批准后，在第 0 节将 Status 设为 Approved。只有 Status = Approved 后才能开始实现。
4. 开始实现时，将 Status 设为 In implementation，并随着进展持续更新，使其始终反映最新情况。
5. 实现期间，填写 DoD 检查清单（第 9 节）。所有项目均已勾选后，DoD 才算完成。
6. DoD 完成后，在第 0 节将 Status 设为 Done，并立即在分支 feature/... 上创建 PR。
7. 实现期间的任何变更都必须先更新 SPEC。

第 4 阶段——验证

4.1–4.3 验证

运行验证脚本：

bash .claude/skills/create-agent-harness/scripts/validate-harness.sh

如果从此仓库调用该技能，请先复制脚本，再在目标仓库中运行；或者从 scripts/validate-harness.sh 手动复制命令。

4.4–4.7 验证产物

反模式、质量检查清单、最终报告模板和交接步骤见 references/validation-artifacts.md。

示例

输入：“为这个 Node 仓库配置 AI Agent”——仓库尚无 harness

输出：

1. 前置检查：确认工作区干净，创建分支 feature/claude-{YYYYMMDD}-bootstrap-claude-harness。
2. 探索摘要引用 package.json（Node、Jest、ESLint）和 .github/workflows/ci.yml（npm ci && npm test && npm run lint）；未发现旧版 harness。暂停并等待确认。
3. 确认后：创建 .claude/，其中包含 settings.json、rules/global-rules.md、五个子 Agent、记忆文件，并在根目录写入 CLAUDE.md。
4. 验证 4.1 返回空结果，4.2 和 4.3 全部通过。
5. 在功能分支上提交，并向 main 提议创建拉取请求。

输入：“将此仓库的 harness 迁移到 Claude”——仓库包含 AGENTS.md 和 .agents/

**输出：**探索阶段列出每个旧版产物，并按 origin → destination → action 格式打印迁移计划。确认后，将 AGENTS.md 合并到 CLAUDE.md，将 .agents/rules/* 转为 .claude/rules/* 并将 applyTo 转换为 paths:，将 .agents/subagents/* 转为 .claude/agents/* 并将 allowed-tools 转换为 tools，然后使用 git rm 删除原文件。验证 4.1 确认没有遗留旧版内容。

输入：“为这个仓库创建一个 GEMINI.md”

**输出：**拒绝——仅适用于 Gemini 的 harness 不在范围内。说明该技能以 CLAUDE.md 作为唯一信息源，并通过精简的 AGENTS.md 进行引用；仅当明确指定目标平台时才生成平台专属目录，且绝不将其作为事实来源。

输入：“Agent 不记得昨天做过什么”

**输出：**运行完整流程，报告只有记忆产物缺失，并生成 .claude/memory/memory.md、.claude/memory/{YYYYMMDD}-memory.md，以及在 CLAUDE.md、global-rules.md 和 Agent 循环中的连接配置。

故障排除

问题	修复方法
技能询问要做什么，而不是直接开始	重新阅读“立即执行”——调用时即开始第 0 阶段
当前分支是 main、master 或 develop	停止，并在进行任何写入之前创建专用功能分支
工作区中有无关更改	停止并询问——绝不混合处理
探索期间找不到某条命令	写入 TODO: define {command}，并在关卡处提出；绝不自行编造
迁移后仍存在旧版产物	验证 4.1 返回非空结果——返回第 2 阶段
规则从未生效	它使用了 applyTo；Claude Code 只会解析 paths:
子 Agent 从未触发	name: 与文件名不匹配，或 description 缺少 "Use PROACTIVELY"
尽管有 .claudeignore，文件仍可读取	CLI 不会读取该文件——将这些模式移到 permissions.deny
未能阻止推送到 main	分支保护由服务器端实施；本地钩子无法限定 git push 的分支
CI 工作流静默失败	检查 runs-on:——在企业仓库中绝不假设是 ubuntu-latest
重新运行时重复生成产物	幂等性遭到破坏——生成前先检测已存在的内容
记忆文件夹不断增长并污染上下文	只读取最近的 3 个带日期文件；整理后 memory.md 不超过 100 行
Agent 信任过时的记忆条目	即时对照代码进行验证，然后追加一条 SUPERSEDED: 记录

何时使用相关技能

需求	技能
为 Agent 构建 MCP 服务	building-mcp-servers
GitHub Actions Agent 工作流（gh-aw）	github-agentic-workflows
完整的 Devin 操作手册，包含确认关卡	devin/playbooks/create-agents
Composio MCP 设置与身份验证	composio-mcp
NotebookLM MCP 设置与身份验证	notebooklm-mcp

参考资料

• agents.md 规范
• OpenAI — Harness Engineering
• Anthropic — 构建高效 Agent
• Claude Code — 记忆与导入
• Claude Code — 子 Agent
• Claude Code — 设置与权限
• Claude Code — 钩子
• Claude Code — 斜杠命令
• Devin CLI — 可扩展性
• Martin Fowler — Harness Engineering
• LangChain — Agent Harness 剖析
• awesome-ai-conventions
• Agent Skills 规范
• Model Context Protocol
• GitHub Agentic Workflows
• Awesome Harness Engineering

给大模型的指令： 需要时查阅这些参考资料，以遵循社区惯例并调整代码库。将其作为 Harness Engineering 最佳实践的指南，并及时了解平台的发展。