mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-15 02:42:45 +08:00
0cc5101c0e
- Introduced Phase 2.5: Consolidation Agent to summarize analysis outputs and generate design overviews. - Added Phase 4: Document Assembly to create index-style documents linking chapter files. - Implemented Phase 5: Compliance Review & Iterative Refinement for CPCC compliance checks and updates. - Established CPCC Compliance Requirements document outlining mandatory sections and validation functions. - Created a base template for analysis agents to ensure consistency and efficiency in execution.
399 lines
10 KiB
Markdown
399 lines
10 KiB
Markdown
# Phase 4: Specifications & Templates Generation
|
|
|
|
Generate domain requirements, quality standards, agent templates, and action catalogs.
|
|
|
|
## Objective
|
|
|
|
Generate comprehensive specifications and templates:
|
|
- Domain requirements document with validation function
|
|
- Quality standards with automated check system
|
|
- Agent base template with prompt structure
|
|
- Action catalog for autonomous mode (conditional)
|
|
|
|
## Input
|
|
|
|
**File Dependencies**:
|
|
- `skill-config.json` (from Phase 1)
|
|
- `.claude/skills/{skill-name}/` directory (from Phase 2)
|
|
- Generated phase/action files (from Phase 3)
|
|
|
|
**Required Information**:
|
|
- Skill name, display name, description
|
|
- Execution mode (determines if action-catalog.md is generated)
|
|
- Output format and location
|
|
- Phase/action definitions
|
|
|
|
## Output
|
|
|
|
**Generated Files**:
|
|
|
|
| File | Purpose | Generation Condition |
|
|
|------|---------|---------------------|
|
|
| `specs/{skill-name}-requirements.md` | Domain requirements with validation | Always |
|
|
| `specs/quality-standards.md` | Quality evaluation criteria | Always |
|
|
| `templates/agent-base.md` | Agent prompt template | Always |
|
|
| `specs/action-catalog.md` | Action dependency graph and selection priority | Autonomous/Hybrid mode only |
|
|
|
|
**File Structure**:
|
|
|
|
**Domain Requirements** (`specs/{skill-name}-requirements.md`):
|
|
```markdown
|
|
# {display_name} Requirements
|
|
- When to Use (phase/action reference table)
|
|
- Domain Requirements (功能要求, 输出要求, 质量要求)
|
|
- Validation Function (JavaScript code)
|
|
- Error Handling (recovery strategies)
|
|
```
|
|
|
|
**Quality Standards** (`specs/quality-standards.md`):
|
|
```markdown
|
|
# Quality Standards
|
|
- Quality Dimensions (Completeness 25%, Consistency 25%, Accuracy 25%, Usability 25%)
|
|
- Quality Gates (Pass ≥80%, Review 60-79%, Fail <60%)
|
|
- Issue Classification (Errors, Warnings, Info)
|
|
- Automated Checks (runQualityChecks function)
|
|
```
|
|
|
|
**Agent Base** (`templates/agent-base.md`):
|
|
```markdown
|
|
# Agent Base Template
|
|
- 通用 Prompt 结构 (ROLE, PROJECT CONTEXT, TASK, CONSTRAINTS, OUTPUT_FORMAT, QUALITY_CHECKLIST)
|
|
- 变量说明 (workDir, output_path)
|
|
- 返回格式 (AgentReturn interface)
|
|
- 角色定义参考 (phase/action specific agents)
|
|
```
|
|
|
|
**Action Catalog** (`specs/action-catalog.md`, Autonomous/Hybrid only):
|
|
```markdown
|
|
# Action Catalog
|
|
- Available Actions (table with Purpose, Preconditions, Effects)
|
|
- Action Dependencies (Mermaid diagram)
|
|
- State Transitions (state machine table)
|
|
- Selection Priority (ordered action list)
|
|
```
|
|
|
|
## Decision Logic
|
|
|
|
```
|
|
Decision (execution_mode check):
|
|
├─ mode === 'sequential' → Generate 3 files only
|
|
│ └─ Files: requirements.md, quality-standards.md, agent-base.md
|
|
│
|
|
├─ mode === 'autonomous' → Generate 4 files
|
|
│ ├─ Files: requirements.md, quality-standards.md, agent-base.md
|
|
│ └─ Additional: action-catalog.md (with action dependencies)
|
|
│
|
|
└─ mode === 'hybrid' → Generate 4 files
|
|
├─ Files: requirements.md, quality-standards.md, agent-base.md
|
|
└─ Additional: action-catalog.md (with hybrid logic)
|
|
```
|
|
|
|
## Execution Protocol
|
|
|
|
```javascript
|
|
// Phase 4: Generate Specifications & Templates
|
|
// Reference: phases/04-specs-templates.md
|
|
|
|
// Load config and setup
|
|
const config = JSON.parse(Read(`${workDir}/skill-config.json`));
|
|
const skillDir = `.claude/skills/${config.skill_name}`;
|
|
|
|
// Ensure specs and templates directories exist (created in Phase 2)
|
|
// skillDir structure: phases/, specs/, templates/
|
|
|
|
// Step 1: Generate domain requirements
|
|
const domainRequirements = `# ${config.display_name} Requirements
|
|
|
|
${config.description}
|
|
|
|
## When to Use
|
|
|
|
| Phase | Usage | Reference |
|
|
|-------|-------|-----------|
|
|
${config.execution_mode === 'sequential' ?
|
|
config.sequential_config.phases.map((p, i) =>
|
|
`| Phase ${i+1} | ${p.name} | ${p.id}.md |`
|
|
).join('\n') :
|
|
`| Orchestrator | 动作选择 | orchestrator.md |
|
|
| Actions | 动作执行 | actions/*.md |`}
|
|
|
|
---
|
|
|
|
## Domain Requirements
|
|
|
|
### 功能要求
|
|
|
|
- [ ] 要求1: TODO
|
|
- [ ] 要求2: TODO
|
|
- [ ] 要求3: TODO
|
|
|
|
### 输出要求
|
|
|
|
- [ ] 格式: ${config.output.format}
|
|
- [ ] 位置: ${config.output.location}
|
|
- [ ] 命名: ${config.output.filename_pattern}
|
|
|
|
### 质量要求
|
|
|
|
- [ ] 完整性: 所有必需内容存在
|
|
- [ ] 一致性: 术语和格式统一
|
|
- [ ] 准确性: 内容基于实际分析
|
|
|
|
## Validation Function
|
|
|
|
\`\`\`javascript
|
|
function validate${toPascalCase(config.skill_name)}(output) {
|
|
const checks = [
|
|
// TODO: 添加验证规则
|
|
{ name: "格式正确", pass: output.format === "${config.output.format}" },
|
|
{ name: "内容完整", pass: output.content?.length > 0 }
|
|
];
|
|
|
|
return {
|
|
passed: checks.filter(c => c.pass).length,
|
|
total: checks.length,
|
|
details: checks
|
|
};
|
|
}
|
|
\`\`\`
|
|
|
|
## Error Handling
|
|
|
|
| Error | Recovery |
|
|
|-------|----------|
|
|
| 输入数据缺失 | 返回明确错误信息 |
|
|
| 处理超时 | 缩小范围，重试 |
|
|
| 输出验证失败 | 记录问题，人工审核 |
|
|
`;
|
|
|
|
Write(`${skillDir}/specs/${config.skill_name}-requirements.md`, domainRequirements);
|
|
|
|
// Step 2: Generate quality standards
|
|
const qualityStandards = `# Quality Standards
|
|
|
|
${config.display_name} 的质量评估标准。
|
|
|
|
## Quality Dimensions
|
|
|
|
### 1. Completeness (完整性) - 25%
|
|
|
|
| 要求 | 权重 | 检查方式 |
|
|
|------|------|----------|
|
|
| 所有必需输出存在 | 10 | 文件检查 |
|
|
| 内容覆盖完整 | 10 | 内容分析 |
|
|
| 无占位符残留 | 5 | 文本搜索 |
|
|
|
|
### 2. Consistency (一致性) - 25%
|
|
|
|
| 方面 | 检查 |
|
|
|------|------|
|
|
| 术语 | 同一概念使用相同术语 |
|
|
| 格式 | 标题层级、代码块格式一致 |
|
|
| 风格 | 语气和表达方式统一 |
|
|
|
|
### 3. Accuracy (准确性) - 25%
|
|
|
|
| 要求 | 说明 |
|
|
|------|------|
|
|
| 数据正确 | 引用和数据无错误 |
|
|
| 逻辑正确 | 流程和关系描述准确 |
|
|
| 代码正确 | 代码示例可运行 |
|
|
|
|
### 4. Usability (可用性) - 25%
|
|
|
|
| 指标 | 目标 |
|
|
|------|------|
|
|
| 可读性 | 结构清晰，易于理解 |
|
|
| 可导航 | 目录和链接正确 |
|
|
| 可操作 | 步骤明确，可执行 |
|
|
|
|
## Quality Gates
|
|
|
|
| Gate | Threshold | Action |
|
|
|------|-----------|--------|
|
|
| Pass | ≥ 80% | 输出最终产物 |
|
|
| Review | 60-79% | 处理警告后继续 |
|
|
| Fail | < 60% | 必须修复 |
|
|
|
|
## Issue Classification
|
|
|
|
### Errors (Must Fix)
|
|
|
|
- 必需输出缺失
|
|
- 数据错误
|
|
- 代码不可运行
|
|
|
|
### Warnings (Should Fix)
|
|
|
|
- 格式不一致
|
|
- 内容深度不足
|
|
- 缺少示例
|
|
|
|
### Info (Nice to Have)
|
|
|
|
- 优化建议
|
|
- 增强机会
|
|
|
|
## Automated Checks
|
|
|
|
\`\`\`javascript
|
|
function runQualityChecks(workDir) {
|
|
const results = {
|
|
completeness: checkCompleteness(workDir),
|
|
consistency: checkConsistency(workDir),
|
|
accuracy: checkAccuracy(workDir),
|
|
usability: checkUsability(workDir)
|
|
};
|
|
|
|
results.overall = (
|
|
results.completeness * 0.25 +
|
|
results.consistency * 0.25 +
|
|
results.accuracy * 0.25 +
|
|
results.usability * 0.25
|
|
);
|
|
|
|
return {
|
|
score: results.overall,
|
|
gate: results.overall >= 80 ? 'pass' :
|
|
results.overall >= 60 ? 'review' : 'fail',
|
|
details: results
|
|
};
|
|
}
|
|
\`\`\`
|
|
`;
|
|
|
|
Write(`${skillDir}/specs/quality-standards.md`, qualityStandards);
|
|
|
|
// Step 3: Generate agent base template
|
|
const agentBase = `# Agent Base Template
|
|
|
|
${config.display_name} 的 Agent 基础模板。
|
|
|
|
## 通用 Prompt 结构
|
|
|
|
\`\`\`
|
|
[ROLE] 你是{角色}，专注于{职责}。
|
|
|
|
[PROJECT CONTEXT]
|
|
Skill: ${config.skill_name}
|
|
目标: ${config.description}
|
|
|
|
[TASK]
|
|
{任务描述}
|
|
- 输出: {output_path}
|
|
- 格式: ${config.output.format}
|
|
|
|
[CONSTRAINTS]
|
|
- 约束1
|
|
- 约束2
|
|
|
|
[OUTPUT_FORMAT]
|
|
1. 执行任务
|
|
2. 返回 JSON 简要信息
|
|
|
|
[QUALITY_CHECKLIST]
|
|
- [ ] 输出格式正确
|
|
- [ ] 内容完整无遗漏
|
|
- [ ] 无占位符残留
|
|
\`\`\`
|
|
|
|
## 变量说明
|
|
|
|
| 变量 | 来源 | 示例 |
|
|
|------|------|------|
|
|
| {workDir} | 运行时 | .workflow/.scratchpad/${config.skill_name}-xxx |
|
|
| {output_path} | 配置 | ${config.output.location}/${config.output.filename_pattern} |
|
|
|
|
## 返回格式
|
|
|
|
\`\`\`typescript
|
|
interface AgentReturn {
|
|
status: "completed" | "partial" | "failed";
|
|
output_file: string;
|
|
summary: string; // Max 50 chars
|
|
stats?: {
|
|
items_processed?: number;
|
|
errors?: number;
|
|
};
|
|
}
|
|
\`\`\`
|
|
|
|
## 角色定义参考
|
|
|
|
${config.execution_mode === 'sequential' ?
|
|
config.sequential_config.phases.map((p, i) =>
|
|
`- **Phase ${i+1} Agent**: ${p.name} 专家`
|
|
).join('\n') :
|
|
config.autonomous_config.actions.map(a =>
|
|
`- **${a.name} Agent**: ${a.description || a.name + ' 执行者'}`
|
|
).join('\n')}
|
|
`;
|
|
|
|
Write(`${skillDir}/templates/agent-base.md`, agentBase);
|
|
|
|
// Step 4: Conditional - Generate action catalog for autonomous/hybrid mode
|
|
if (config.execution_mode === 'autonomous' || config.execution_mode === 'hybrid') {
|
|
const actionCatalog = `# Action Catalog
|
|
|
|
${config.display_name} 的可用动作目录。
|
|
|
|
## Available Actions
|
|
|
|
| Action | Purpose | Preconditions | Effects |
|
|
|--------|---------|---------------|---------|
|
|
${config.autonomous_config.actions.map(a =>
|
|
`| [${a.id}](../phases/actions/${a.id}.md) | ${a.description || a.name} | ${a.preconditions?.join(', ') || '-'} | ${a.effects?.join(', ') || '-'} |`
|
|
).join('\n')}
|
|
|
|
## Action Dependencies
|
|
|
|
\`\`\`mermaid
|
|
graph TD
|
|
${config.autonomous_config.actions.map((a, i, arr) => {
|
|
if (i === 0) return ` ${a.id.replace(/-/g, '_')}[${a.name}]`;
|
|
const prev = arr[i-1];
|
|
return ` ${prev.id.replace(/-/g, '_')} --> ${a.id.replace(/-/g, '_')}[${a.name}]`;
|
|
}).join('\n')}
|
|
\`\`\`
|
|
|
|
## State Transitions
|
|
|
|
| From State | Action | To State |
|
|
|------------|--------|----------|
|
|
| pending | action-init | running |
|
|
${config.autonomous_config.actions.slice(1).map(a =>
|
|
`| running | ${a.id} | running |`
|
|
).join('\n')}
|
|
| running | action-complete | completed |
|
|
| running | action-abort | failed |
|
|
|
|
## Selection Priority
|
|
|
|
当多个动作的前置条件都满足时，按以下优先级选择：
|
|
|
|
${config.autonomous_config.actions.map((a, i) =>
|
|
`${i + 1}. \`${a.id}\` - ${a.name}`
|
|
).join('\n')}
|
|
`;
|
|
|
|
Write(`${skillDir}/specs/action-catalog.md`, actionCatalog);
|
|
}
|
|
|
|
// Helper function
|
|
function toPascalCase(str) {
|
|
return str.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('');
|
|
}
|
|
|
|
// Phase output summary
|
|
console.log('Phase 4 complete: Generated specs and templates');
|
|
```
|
|
|
|
## Next Phase
|
|
|
|
→ [Phase 5: Validation](05-validation.md)
|
|
|
|
**Data Flow to Phase 5**:
|
|
- All generated files in `specs/` and `templates/`
|
|
- skill-config.json for validation reference
|
|
- Complete skill directory structure ready for final validation
|