project-alignment-validation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Alignment Validation Skill

项目一致性校验Skill

Comprehensive patterns for validating alignment between features, code, and PROJECT.md. Focuses on semantic validation (intent and goals) rather than literal pattern matching.

用于校验功能、代码与PROJECT.md之间一致性的全面模式。聚焦于语义验证（意图与目标）而非字面匹配。

When This Skill Activates

该Skill的激活场景

Validating feature alignment with PROJECT.md
Assessing gaps between current state and goals
Resolving conflicts between documentation and implementation
Checking GOALS, SCOPE, CONSTRAINTS, ARCHITECTURE compliance
Keywords: "alignment", "PROJECT.md", "validation", "GOALS", "SCOPE", "semantic", "gap"

校验功能与PROJECT.md的一致性
评估当前状态与目标之间的差距
解决文档与实现之间的冲突
检查是否符合GOALS、SCOPE、CONSTRAINTS、ARCHITECTURE要求
关键词："alignment"、"PROJECT.md"、"validation"、"GOALS"、"SCOPE"、"semantic"、"gap"

Core Validation Approach

核心校验方法

Semantic Validation Philosophy

语义校验理念

Semantic validation focuses on understanding the intent and purpose behind requirements, not just literal text matching.

Key Principles:

Intent over Syntax: Validate that features serve project goals, not just match keywords
Context-Aware: Consider project phase, constraints, and strategic direction
Progressive Assessment: Start with high-level goals, drill down to details
Graceful Gaps: Identify gaps without blocking progress; prioritize by impact

Contrast with Literal Validation:

❌ Literal: "Feature must contain keyword 'authentication'"
✅ Semantic: "Feature must support project's user management goals"

语义校验聚焦于理解需求背后的意图与目的，而非仅仅匹配字面文本。

核心原则：

意图优先于语法：校验功能是否服务于项目目标，而非仅匹配关键词
上下文感知：考虑项目阶段、约束条件与战略方向
渐进式评估：从高层目标入手，逐步深入细节
灵活处理差距：识别差距但不阻碍进度；按影响程度优先处理

与字面校验的对比：

❌ 字面校验："功能必须包含关键词'authentication'"
✅ 语义校验："功能必须支持项目的用户管理目标"

PROJECT.md Structure

PROJECT.md结构

Four Core Sections

四个核心章节

Every PROJECT.md should define:

GOALS: Strategic objectives and desired outcomes
SCOPE: What's in scope (and explicitly out of scope)
CONSTRAINTS: Technical, resource, and policy limitations
ARCHITECTURE: High-level design principles and patterns

每份PROJECT.md都应定义：

GOALS：战略目标与预期成果
SCOPE：包含（及明确排除）的范围
CONSTRAINTS：技术、资源与政策限制
ARCHITECTURE：高层设计原则与模式

Validation Checklist

校验清单

For each feature, validate against all four sections:

markdown

undefined

针对每个功能，需对照所有四个章节进行校验：

markdown

undefined

Alignment Checklist

一致性校验清单

GOALS Alignment

GOALS一致性

Feature serves at least one project goal
Feature doesn't conflict with any goals
Feature priority matches goal priority
Success metrics align with goal metrics

功能至少服务于一个项目目标
功能与任何目标无冲突
功能优先级与目标优先级匹配
成功指标与目标指标一致

SCOPE Alignment

SCOPE一致性

Feature is explicitly in scope
Feature doesn't overlap with out-of-scope items
Feature respects scope boundaries
Feature dependencies are in scope

功能明确在范围内
功能与范围外内容无重叠
功能遵守范围边界
功能依赖项在范围内

CONSTRAINTS Alignment

CONSTRAINTS一致性

Feature respects technical constraints
Feature works within resource constraints
Feature complies with policy constraints
Feature considers timeline constraints

功能遵守技术约束
功能在资源限制内运行
功能符合政策约束
功能考虑时间线约束

ARCHITECTURE Alignment

ARCHITECTURE一致性

Feature follows architectural patterns
Feature integrates with existing components
Feature respects design principles
Feature maintains architectural consistency


See: `docs/alignment-checklist.md` for detailed checklist with examples

---

功能遵循架构模式
功能与现有组件集成
功能遵守设计原则
功能保持架构一致性


详见：`docs/alignment-checklist.md` 获取含示例的详细校验清单

---

Gap Assessment Methodology

差距评估方法

Identify Gaps

识别差距

Gaps occur when current state doesn't match desired state defined in PROJECT.md.

Types of Gaps:

Feature Gaps: Missing functionality needed to achieve goals
Documentation Gaps: PROJECT.md doesn't reflect actual implementation
Constraint Gaps: Implementation violates stated constraints
Architectural Gaps: Code doesn't follow design principles

当当前状态与PROJECT.md定义的预期状态不匹配时，就会出现差距。

差距类型：

功能差距：缺少实现目标所需的功能
文档差距：PROJECT.md未反映实际实现情况
约束差距：实现违反了既定约束
架构差距：代码未遵循设计原则

Prioritize Gaps

优先级排序

Not all gaps are equal. Prioritize by:

Impact Assessment:

Critical: Blocks primary goals, violates hard constraints
High: Significantly delays goals, creates technical debt
Medium: Slows progress, reduces quality
Low: Minor inconvenience, cosmetic issues

Effort Estimation:

Quick Win: High impact, low effort (prioritize)
Strategic: High impact, high effort (plan carefully)
Tactical: Medium impact, medium effort (schedule)
Defer: Low impact, high effort (defer or drop)

并非所有差距的重要性都相同。按以下维度排序：

影响评估：

关键：阻碍主要目标，违反硬性约束
高：显著延迟目标达成，产生技术债务
中：减缓进度，降低质量
低：轻微不便，表面性问题

工作量估算：

快速见效：高影响，低工作量（优先处理）
战略级：高影响，高工作量（仔细规划）
战术级：中等影响，中等工作量（安排日程）
延后处理：低影响，高工作量（延后或放弃）

Document Gaps

记录差距

Use standardized gap assessment template:

markdown

undefined

使用标准化的差距评估模板：

markdown

undefined

Gap Assessment

差距评估

Gap Summary

差距摘要

Type: [Feature/Documentation/Constraint/Architectural]
Impact: [Critical/High/Medium/Low]
Effort: [Quick Win/Strategic/Tactical/Defer]

类型：[功能/文档/约束/架构]
影响：[关键/高/中/低]
工作量：[快速见效/战略级/战术级/延后处理]

Current State

当前状态

[Describe what exists today]

[描述当前存在的情况]

Desired State

预期状态

[Describe what PROJECT.md defines]

[描述PROJECT.md定义的内容]

Gap Details

差距详情

[Explain the specific differences]

[解释具体差异]

Recommended Action

建议行动

[Propose concrete steps to close gap]

[提出缩小差距的具体步骤]

Dependencies

依赖项

[List any prerequisites or blockers]


See: `docs/gap-assessment-methodology.md` for complete methodology

---

[列出任何先决条件或阻碍因素]


详见：`docs/gap-assessment-methodology.md` 获取完整方法

---

Conflict Resolution Patterns

冲突解决模式

Detect Conflicts

检测冲突

Conflicts arise when:

Feature serves one goal but violates another
Feature is in scope but violates constraints
Implementation follows architecture but misses goals
Documentation and code tell different stories

冲突在以下情况出现：

功能服务于一个目标但违反另一个目标
功能在范围内但违反约束
实现遵循架构但未达成目标
文档与代码表述不一致

Resolution Strategies

解决策略

Strategy 1: Update PROJECT.md (Documentation is wrong)

Current state is correct, PROJECT.md is outdated
Update PROJECT.md to reflect actual strategic direction
Validate changes with stakeholders

Strategy 2: Modify Feature (Implementation is wrong)

PROJECT.md is correct, feature needs adjustment
Refactor feature to align with goals/scope/constraints
May require re-planning or re-architecting

Strategy 3: Negotiate Compromise (Both partially correct)

Find middle ground that serves goals within constraints
May require adjusting both PROJECT.md and implementation
Document trade-offs and rationale

Strategy 4: Escalate Decision (Requires stakeholder input)

Conflict involves strategic direction or priorities
Present options with trade-offs to decision makers
Document decision and update PROJECT.md

See:

docs/conflict-resolution-patterns.md

for detailed resolution workflows

策略1：更新PROJECT.md（文档有误）

当前状态正确，PROJECT.md已过时
更新PROJECT.md以反映实际战略方向
与利益相关者确认变更

策略2：修改功能（实现有误）

PROJECT.md正确，功能需要调整
重构功能以符合目标/范围/约束
可能需要重新规划或重新架构

策略3：协商妥协（双方部分正确）

找到既能服务目标又符合约束的折中方案
可能需要同时调整PROJECT.md与实现
记录权衡与理由

策略4：升级决策（需利益相关者输入）

冲突涉及战略方向或优先级
向决策者展示含权衡的选项
记录决策并更新PROJECT.md

详见：

docs/conflict-resolution-patterns.md

获取详细解决流程

Progressive Disclosure

渐进式披露

This skill provides layered documentation:

该Skill提供分层文档：

Always Available (Frontmatter)

始终可用（前置内容）

Skill name and description
Keywords for auto-activation
Quick reference to core concepts

Skill名称与描述
自动激活的关键词
核心概念快速参考

Available in Full Content

完整内容中可用

Detailed alignment checklist
Semantic validation approach
Gap assessment methodology
Conflict resolution patterns
Templates for reports and assessments
Real-world examples and scenarios

详细的一致性校验清单
语义校验方法
差距评估方法
冲突解决模式
报告与评估模板
真实场景与示例

Load Full Content When Needed

需要时加载完整内容

Creating alignment reports
Assessing project health
Resolving complex conflicts
Onboarding new projects
Validating strategic changes

创建一致性报告
评估项目健康状况
解决复杂冲突
新项目入职培训
校验战略变更

Documentation Resources

文档资源

Comprehensive Guides

综合指南

```
docs/alignment-checklist.md
```
- Standard validation steps for GOALS/SCOPE/CONSTRAINTS/ARCHITECTURE
```
docs/semantic-validation-approach.md
```
- Semantic vs literal validation philosophy
```
docs/gap-assessment-methodology.md
```
- Identify, prioritize, and document gaps
```
docs/conflict-resolution-patterns.md
```
- Strategies for resolving alignment conflicts

```
docs/alignment-checklist.md
```
- GOALS/SCOPE/CONSTRAINTS/ARCHITECTURE的标准校验步骤
```
docs/semantic-validation-approach.md
```
- 语义与字面校验理念对比
```
docs/gap-assessment-methodology.md
```
- 识别、排序与记录差距
```
docs/conflict-resolution-patterns.md
```
- 解决一致性冲突的策略

Templates

模板

```
templates/alignment-report-template.md
```
- Standard structure for alignment reports
```
templates/gap-assessment-template.md
```
- Gap documentation template

templates/conflict-resolution-template.md

- Conflict resolution workflow

```
templates/alignment-report-template.md
```
- 一致性报告的标准结构
```
templates/gap-assessment-template.md
```
- 差距记录模板

templates/conflict-resolution-template.md

- 冲突解决流程

Examples

示例

```
examples/alignment-scenarios.md
```
- Common scenarios and recommended fixes
```
examples/misalignment-examples.md
```
- Real-world misalignment cases

examples/project-md-structure-example.md

- Well-structured PROJECT.md

```
examples/alignment-scenarios.md
```
- 常见场景与推荐修复方案
```
examples/misalignment-examples.md
```
- 真实的不一致案例

examples/project-md-structure-example.md

- 结构良好的PROJECT.md示例

Integration Points

集成点

Agents

alignment-validator: Use checklist for quick validation
alignment-analyzer: Use gap assessment for detailed analysis
project-progress-tracker: Use GOALS validation for progress tracking

alignment-validator：使用校验清单进行快速校验
alignment-analyzer：使用差距评估进行详细分析
project-progress-tracker：使用GOALS校验进行进度跟踪

Hooks

validate_project_alignment.py: Use checklist for pre-commit validation
auto_update_project_progress.py: Use GOALS tracking patterns
enforce_pipeline_complete.py: Use alignment patterns for feature validation

validate_project_alignment.py：使用校验清单进行提交前校验
auto_update_project_progress.py：使用GOALS跟踪模式
enforce_pipeline_complete.py：使用一致性模式进行功能校验

Libraries

alignment_assessor.py: Use gap assessment methodology
project_md_updater.py: Use conflict resolution patterns
brownfield_retrofit.py: Use alignment checklist for retrofit analysis

alignment_assessor.py：使用差距评估方法
project_md_updater.py：使用冲突解决模式
brownfield_retrofit.py：使用一致性校验清单进行改造分析

Best Practices

最佳实践

Validate Early: Check alignment before implementation, not after
Document Decisions: Record why features align or don't align
Update Iteratively: PROJECT.md should evolve with project understanding
Prioritize Gaps: Not all gaps are critical; focus on high-impact items
Semantic First: Understand intent before applying validation rules
Graceful Degradation: Alignment issues are warnings, not blockers (unless critical)

提前校验：在实现前检查一致性，而非事后
记录决策：记录功能是否一致的原因
迭代更新：PROJECT.md应随项目认知进化
优先处理差距：并非所有差距都关键；聚焦高影响项
语义优先：在应用校验规则前先理解意图
优雅降级：一致性问题是警告，而非阻碍（除非是关键问题）

Success Criteria

成功标准

Feature validation is successful when:

✓ Feature clearly serves at least one project goal
✓ Feature is explicitly in scope (or scope updated to include it)
✓ Feature respects all constraints (or constraints documented as trade-offs)
✓ Feature follows architectural patterns (or deviations justified)
✓ Gaps are identified, prioritized, and tracked
✓ Conflicts are resolved with documented rationale

Last Updated: 2025-11-16 Version: 1.0.0 Related Skills: semantic-validation, file-organization, research-patterns, project-management

功能校验成功的标志：

✓ 功能明确服务于至少一个项目目标
✓ 功能明确在范围内（或已更新范围以包含该功能）
✓ 功能遵守所有约束（或已记录约束权衡）
✓ 功能遵循架构模式（或已记录偏差理由）
✓ 差距已识别、排序并跟踪
✓ 冲突已解决并记录理由

最后更新：2025-11-16 版本：1.0.0 相关Skills：semantic-validation, file-organization, research-patterns, project-management