Back to Details

project-context

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project Context

项目上下文

프로젝트의 코드 구조(사실)와 아키텍처 의도(WHY)를 문서화하여 컨텍스트 효율을 극대화합니다.
通过记录项目的代码结构（事实）和架构意图（WHY），最大化上下文效率。

Instructions

操作指南

워크플로우 1: Codemap 생성

工作流1：生成Codemap

목적: 코드 구조 사실 기록 → 
.codemap.md
$ARGUMENTS: 
quick
| 
full
| (없음 = 기본)
인자모드포함 내용
(없음)기본구조 + 핵심 파일 목록 + 의존성
quick
빠름디렉토리 구조만
full
상세구조 + 파일 요약 + 주요 함수/클래스
프로세스:
  1. 프로젝트 분석 (Glob, 의존성 파일 읽기)
  2. .codemap.md
    생성:
    markdown
    # Project Codemap
> Generated: {날짜} | Mode: {모드}

## 디렉토리 구조
{tree 형태}

## 핵심 파일
{파일 목록 + 역할}

## 의존성 요약
{주요 의존성}

## 진입점
{실행 명령어 → 진입 파일}
目的：记录代码结构事实 → 
.codemap.md
$ARGUMENTS: 
quick
| 
full
| (无 = 默认)
参数模式包含内容
(无)默认结构 + 核心文件列表 + 依赖
quick
快速模式仅目录结构
full
详细模式结构 + 文件摘要 + 主要函数/类
流程:
  1. 项目分析（Glob、读取依赖文件）
  2. 生成
    .codemap.md
    :
    markdown
    # Project Codemap
> Generated: {날짜} | Mode: {모드}

## 目录结构
{树形结构}

## 核心文件
{文件列表 + 作用}

## 依赖摘要
{主要依赖}

## 入口点
{执行命令 → 入口文件}

워크플로우 2: Architecture 문서화

工作流2：架构文档化

목적: 아키텍처 의도 기록 → 
ARCHITECTURE.md
생성 (ARCHITECTURE.md가 없을 때):
  1. 코드베이스 분석 (디렉토리, 설정, 진입점)
  2. 사용자에게 의도 질문:
    • "이 프로젝트에서 가장 중요한 제약은?"
    • "앞으로 확장할 계획이 있는 부분은?"
    • "이 구조를 선택한 이유는?"
  3. ARCHITECTURE.md
    초안 생성 (템플릿: 
    templates/ARCHITECTURE.md
    )
  4. 반복 협의 → 사용자 승인 시 완료
갱신 (ARCHITECTURE.md가 있을 때):
  1. 현재 문서 읽기
  2. 사용자 요청 반영 (섹션 추가/수정/삭제)
  3. 변경 사항 요약
ARCHITECTURE.md 구조:
섹션내용핵심 질문
Overview한 줄 요약 + 기술 스택이 프로젝트는 무엇인가?
Structure모듈/디렉토리별 책임어디에 무엇이 있는가?
Constraints깨지면 안 되는 규칙무엇을 지켜야 하는가?
Data Flow주요 데이터 흐름 경로데이터가 어떻게 흐르는가?
Extension Points확장 예정/허용 지점앞으로 어떻게 변할 것인가?
Decisions핵심 결정 + WHY왜 이렇게 했는가?
目的：记录架构意图 → 
ARCHITECTURE.md
创建（当ARCHITECTURE.md不存在时）:
  1. 分析代码库（目录、配置、入口点）
  2. 向用户询问意图相关问题:
    • "该项目最重要的约束是什么？"
    • "未来有计划扩展的部分是哪里？"
    • "选择此结构的原因是什么？"
  3. 生成
    ARCHITECTURE.md
    初稿（模板：
    templates/ARCHITECTURE.md
    ）
  4. 反复协作 → 获得用户认可后完成
更新（当ARCHITECTURE.md已存在时）:
  1. 读取当前文档
  2. 反映用户需求（添加/修改/删除章节）
  3. 总结变更内容
ARCHITECTURE.md结构:
章节内容核心问题
Overview一句话摘要 + 技术栈这个项目是做什么的？
Structure各模块/目录的职责各个部分都有什么？
Constraints必须遵守的规则需要遵守什么？
Data Flow主要数据流路径数据是如何流转的？
Extension Points计划/允许扩展的位置未来会如何变化？
Decisions核心决策 + 原因为什么要这么做？

워크플로우 3: Full Context

工作流3：完整上下文

목적: 코드 구조 + 아키텍처 의도 모두 생성
$ARGUMENTS: 
full-context
  1. 워크플로우 1 실행 → 
    .codemap.md
  2. 워크플로우 2 실행 → 
    ARCHITECTURE.md
  3. 완료 안내: 
    ✅ 프로젝트 컨텍스트 생성 완료
- .codemap.md (코드 구조)
- ARCHITECTURE.md (아키텍처 의도)

CLAUDE.md 연동:
  프로젝트 코드맵: @.codemap.md
  프로젝트 아키텍처: @ARCHITECTURE.md
目的：同时生成代码结构 + 架构意图
$ARGUMENTS: 
full-context
  1. 执行工作流1 → 
    .codemap.md
  2. 执行工作流2 → 
    ARCHITECTURE.md
  3. 完成通知: 
    ✅ 项目上下文生成完成
- .codemap.md（代码结构）
- ARCHITECTURE.md（架构意图）

CLAUDE.md联动:
  项目代码地图: @.codemap.md
  项目架构: @ARCHITECTURE.md

중요 원칙

重要原则

  1. Codemap = 사실: 코드에서 읽을 수 있는 구조 (간결하게, 핵심만)
  2. Architecture = 의도: 코드에 없는 WHY (제약, 결정 이유, 확장 방향)
  3. 간결함: Codemap은 핵심 구조만, Architecture는 각 섹션 10-20줄 이내
  4. 살아있는 문서: 구조/아키텍처 변경 시 반드시 갱신
  5. git 관리: ARCHITECTURE.md는 커밋 필수, .codemap.md는 선택적
  1. Codemap = 事实：从代码中可读取的结构（简洁，只保留核心）
  2. Architecture = 意图：代码中没有体现的WHY（约束、决策原因、扩展方向）
  3. 简洁性：Codemap只保留核心结构，Architecture每个章节控制在10-20行以内
  4. 活文档：结构/架构变更时必须更新
  5. git管理：ARCHITECTURE.md必须提交，.codemap.md可选

Examples

示例

Codemap 빠른 생성:
User: "/project-context quick" → .codemap.md 생성 (구조만)
Architecture 정리:
User: "/project-context" (ARCHITECTURE.md 없음)
→ 코드베이스 분석 → 사용자에게 의도 질문 → ARCHITECTURE.md 생성
Full context:
User: "/project-context full-context"
→ .codemap.md + ARCHITECTURE.md 모두 생성
위임 시 활용:
User: "인증 모듈 리팩토링해줘"
→ orchestrator가 ARCHITECTURE.md 확인
→ Constraints 섹션에서 "auth → 외부 의존 허용, 외부 → auth 금지"
→ 위임 프롬프트에 제약 첨부
快速生成Codemap:
用户: "/project-context quick" → 生成.codemap.md（仅结构）
整理架构:
用户: "/project-context"（ARCHITECTURE.md不存在）
→ 分析代码库 → 向用户询问意图问题 → 生成ARCHITECTURE.md
完整上下文:
用户: "/project-context full-context"
→ 同时生成.codemap.md + ARCHITECTURE.md
委派工作时的应用:
用户: "帮我重构认证模块"
→ 协调器查看ARCHITECTURE.md
→ 在Constraints章节中看到"auth → 允许外部依赖，外部 → 禁止访问auth"
→ 在委派提示中添加该约束

연동

联动

도구대상project-context와의 차이
project-context
codemap		코드 구조 (.codemap.md)파일/함수/클래스 사실
project-context
arch		아키텍처 (ARCHITECTURE.md)의도/제약/WHY
ldoc
ADR		개별 결정 기록arch는 전체 그림, ADR은 상세
orchestrator
위임 시 참조Constraints/Structure를 프롬프트에 첨부
언제 뭘 쓰는가:
요청사용이유
"AuthService는 어디 있어?"codemap파일 위치 탐색
"왜 Redis를 선택했어?"ldoc ADR개별 결정 상세
"이 프로젝트 전체 구조는?"arch전체 아키텍처 맥락
"인증 모듈 리팩토링 제약은?"arch Constraints위임 시 제약 확인
"세션 시작, 컨텍스트 필요"full-context코드맵 + 아키텍처
工具目标与project-context的区别
project-context
codemap		代码结构 (.codemap.md)文件/函数/类的事实记录
project-context
arch		架构 (ARCHITECTURE.md)意图/约束/原因
ldoc
ADR		记录单个决策arch是整体视图，ADR是详细记录
orchestrator
委派时参考将Constraints/Structure添加到提示中
何时使用什么工具:
请求使用工具原因
"AuthService在哪里？"codemap查找文件位置
"为什么选择Redis？"ldoc ADR查看单个决策的详细内容
"这个项目的整体结构是怎样的？"arch了解整体架构上下文
"重构认证模块的约束是什么？"arch Constraints委派工作时确认约束
"会话开始，需要上下文"full-context代码地图 + 架构