SuperAPI AI Directory
Partner中文AI newsFavorites
Skillscode-architecture-writer

code-architecture-writer

Office & productivity

View repository

Updated 10-15 20:04

About this skill

Code Architecture Writer

This is a skill that analyzes the codebase and generates architecture/code explanation documents. All explanations are written centered not on "what" but on "why" .

Usage Modes

Mode 1: diff -- Change Description

/code-architecture-writer diff <base_branch> [output.md]
  • base_branch: Comparison base branch (e.g., main)
  • output.md: Output file path (default: CODE_CHANGES_EXPLANATION.md)

Deliverable: A document explaining "why these changes were made" for files changed between branches

Mode 2: flow -- Execution Flow Description

/code-architecture-writer flow <entrypoint.py> [output.md]
  • entrypoint.py: Entry point file path
  • output.md: Output file path (default: ARCHITECTURE_FLOW.md)

Deliverable: An architecture explanation document tracing the entire execution flow from the entry point

Workflow Overview

Phase 1: Target Analysis (대상 분석)
         │
         ├── [diff] git diff base..HEAD → 변경 파일 목록
         └── [flow] entrypoint → import/call 추적
         │
         ▼
Phase 2: Deep Reading (심층 읽기)
         │
         ├── 변경/관련 파일 전체 읽기
         ├── "왜 이 파일인가?" 분석
         ├── 핵심 코드 블록 식별
         └── 함수/클래스 관계 매핑
         │
         ▼
Phase 3: Document Generation (문서 생성)
         │
         ├── 변경 파일 요약 테이블
         ├── 파일별 상세 설명 ("why" 중심)
         ├── 실행 흐름 다이어그램 (ASCII art)
         └── 핵심 설계 결정 요약
         │
         ▼
Phase 4: Quality Check (품질 검증)
         │
         ├── 모든 변경 파일이 설명되었는가?
         ├── 각 변경에 "why" 설명이 있는가?
         ├── 코드 스니펫이 실제 코드와 일치하는가?
         └── 다이어그램이 실제 실행 흐름을 반영하는가?

Phase 1: Target Analysis

Mode: diff

# 1. 변경 파일 목록 추출
git diff <base_branch>..HEAD --stat
git diff <base_branch>..HEAD --name-only

# 2. 총 변경량 파악
git diff <base_branch>..HEAD --shortstat

# 3. 커밋 히스토리 확인 (변경 의도 파악)
git log <base_branch>..HEAD --oneline

# 4. base 커밋 해시 기록
git rev-parse --short <base_branch>

Deliverable: List of changed files + change volume for each file (lines added/removed)

Mode: flow

# 1. 진입점 파일 읽기
Read(entrypoint.py)

# 2. import 문 추출 → 의존 파일 목록 구성
# 3. 호출 체인 추적: main() → 어떤 함수/클래스를 호출하는가?
# 4. 각 호출 대상의 파일 위치 확인

Deliverable: Call chain graph + related file list

Phase 2: Deep Reading

Step 2.1: Full read per file

대상 파일 목록의 각 파일에 대해:
│
├── Read tool로 파일 전체 읽기
├── 파일의 전체 구조 파악 (클래스, 함수, 상수)
└── 핵심 코드 블록 식별 (변경/호출 지점)

Step 2.2: "Why this file?" analysis

Prepare answers to the following questions for each file:

Question Explanation
Why was this file changed/referenced? What role does this file play in the system that made the change necessary
Why not another file? The reason the same change could not have been made in another location
Why was it implemented this way? Advantages of the chosen approach compared to alternatives
What is the relationship with other files? How the changes in this file affect other files

Step 2.3: Function/Class relationship mapping

호출 관계:
  FileA.func_a() → FileB.func_b() → FileC.func_c()

데이터 흐름:
  config.yaml → daemon.__init__() → daemon.get_data()

의존 관계:
  trainer.py ──depends──→ daemon.py ──depends──→ config.yaml

Phase 3: Document Generation

Mode: diff -- Document Structure

Reference: references/diff-explanation-template.md reference

# Code Changes Explanation (vs <base_branch>)

**Base**: `<base_branch>` branch (commit `<hash>`)
**Purpose**: <변경의 핵심 목적 한 줄 요약>
**Date**: <오늘 날짜>
**Total**: <N> files, +<M> lines

---

## 변경 파일 목록

| # | 파일 | 변경량 | 핵심 역할 |
|---|------|--------|----------|
| 1 | `file.py` | +N | **핵심 역할 한 줄** |

---

## 파일 1: file.py -- 왜 이 파일인가?

**<왜 이 파일을 변경해야 했는지 한 문장으로 설명 (볼드)>**

### 변경 A: <변경 설명> (Line N-M)

```python
+코드 스니펫

Why <design decision>? <explanation of the reason>

Dependencies between changes

(ASCII 다이어그램)

Summary of key design decisions

Question Answer
Why X? Because Y. 

### Mode: flow -- 문서 구조

참고: `references/flow-diagram-template.md` 참조

```markdown
# <프로젝트> 실행 흐름

**Purpose**: <진입점>을 실행하면 어떤 코드가 어떤 순서로 호출되는지 정리
**Date**: <오늘 날짜>

---

## 핵심 요약: 한눈에 보는 실행 흐름

entrypoint.py:main() → step1() → step2() ├── [Process A] └── [Process B]


---

## N단계: <단계 이름> (<파일명>)

**파일**: `<파일 경로>`

```python
<핵심 코드 발췌>

Role: <one-line summary> Next: → <next step>

Data flow summary

(ASCII 다이어그램)

Summary of key file roles

File Role One-line description

Why was <key file> modified?

<Provide grounds from an architectural perspective for why this location is appropriate>


---

## Phase 4: Quality Check (품질 검증)

### 검증 체크리스트

| 카테고리 | 항목 | 체크 |
|---------|------|------|
| **완전성** | 모든 변경/관련 파일이 문서에 포함되었는가? | [] |
| **Why 중심** | 각 변경/파일에 "왜" 설명이 있는가? | [] |
| **코드 정확성** | 코드 스니펫이 실제 코드와 일치하는가? | [] |
| **다이어그램** | ASCII 다이어그램이 실제 실행 흐름/의존 관계를 반영하는가? | [] |
| **설계 결정** | 핵심 설계 결정이 질문-답변 형태로 요약되었는가? | [] |
| **의존 관계** | 파일 간 의존 관계가 명확하게 표현되었는가? | [] |
| **일관성** | 변경 파일 목록 테이블의 파일 수와 상세 설명의 파일 수가 일치하는가? | [] |

### 코드 스니펫 검증 프로세스

For every code snippet included in the document: │ ├── [Step 1] Read the corresponding code block from the actual file │ Verify the corresponding line range with the Read tool │ ├── [Step 2] Cross-check the code snippet against the actual code │ - Do the indentation, variable names, and function names match? │ - Are the line numbers accurate? │ └── [Step 3] If a mismatch is found, fix the document Update the code snippet with the Edit tool


### "Why" 설명 검증

각 파일 섹션에서 다음이 포함되어 있는지 확인:

1. **파일 수준 Why**: "왜 이 파일인가?" (볼드 한 문장)
2. **변경 수준 Why**: 각 변경 블록마다 "왜 X인가?" 설명
3. **설계 결정 Why**: 대안 대비 선택한 방식의 근거

---

## 작성 원칙

### 1. "Why" 중심 설명 (가장 중요)

모든 설명의 핵심은 **"왜 이렇게 했는가"** 이다.

(O) Correct example: Why daemon.py? get_train_data_batch()is the only point for the trace -> tensor conversion. In this function, each turn of the rollout is validated, and if an abnormal turn is removed, that turn is not included in the GRPO gradient.

(X) Incorrect example: Added filtering logic to daemon.py.


### 2. 코드 스니펫은 실제 코드에서 발췌

코드 스니펫을 작성할 때 반드시 Read tool로 실제 파일을 읽고 복사한다. 기억에 의존하여 코드를 작성하지 않는다.

(O) Correct process: Read(file_path) → copy the relevant line → insert into document

(X) Incorrect process: Reconstruct the file contents from memory and write them


### 3. 변경량의 정확한 기재

`git diff --stat` 결과를 직접 사용한다.

(O) +160 lines (based on git diff results) (X) about 150 lines added (estimate)


### 4. 의존 관계 ASCII 다이어그램

파일 간 의존 관계를 ASCII art로 표현한다. 화살표 방향은 "의존한다" 또는 "호출한다" 방향.

config.yaml (parameter definition) | v daemon.py (filtering implementation) <---- trainer.py (call) | v train_calc_agent.py (CLI -> config injection)


### 5. 설계 결정 요약 테이블

문서 말미에 핵심 설계 결정을 질문-답변 테이블로 정리한다.

```markdown
| 질문 | 답변 |
|------|------|
| 왜 daemon.py인가? | trace -> tensor 변환의 유일한 지점. gradient 포함 직전에 제거 가능. |
| 왜 chat template인가? | 모델 독립적 토큰 감지. 하드코딩 대비 이식성 향상. |

6. Principles for using Korean

  • Write the explanatory body in Korean
  • Keep code, variable names, and file names as in the original
  • Use English terms as-is for technical terms (do not translate)
    • (O) "gradient", "tensor", "rollout"
    • (X) "기울기", "텐서", "롤아웃"

Usage examples

Example 1: diff mode

사용자: /code-architecture-writer diff main

Claude:
[Phase 1] git diff main..HEAD 분석...
  - 변경 파일 6개 확인
  - 총 +459 lines

[Phase 2] 파일별 심층 읽기...
  - daemon.py: 핵심 필터링 로직 (+160)
  - config.yaml: 파라미터 추가 (+8)
  - trainer.py: 버그 수정 (+1)
  - calc_agent.py: 대화 로깅 (+126)
  - train_calc_agent.py: CLI 옵션 (+71)
  - train_sql_agent.py: CLI 옵션 + config 튜닝 (+98)

[Phase 3] 문서 생성...
  - 파일별 "왜" 설명 작성
  - 의존 관계 다이어그램 작성
  - 설계 결정 요약 테이블 작성

[Phase 4] 품질 검증...
  - 6/6 파일 설명 완료
  - 코드 스니펫 검증 완료

CODE_CHANGES_EXPLANATION.md 저장 완료

Example 2: flow mode

사용자: /code-architecture-writer flow examples/calc_x/train_calc_agent.py

Claude:
[Phase 1] 진입점 분석...
  - train_calc_agent.py:main() 확인
  - import/call 추적 시작

[Phase 2] 호출 체인 추적...
  - main() -> train() -> agl.VERL(config) -> agl.Trainer(...)
  - trainer.fit() -> strategy.execute()
  - 10개 핵심 파일 식별

[Phase 3] 문서 생성...
  - 10단계 실행 흐름 작성
  - 데이터 흐름 다이어그램 작성
  - 핵심 파일 역할 정리 테이블 작성

[Phase 4] 품질 검증...
  - 모든 단계의 코드 스니펫 검증 완료
  - 다이어그램과 실제 흐름 일치 확인

ARCHITECTURE_FLOW.md 저장 완료

Precautions

  1. Preventing code hallucination: All code snippets must be extracted by actually reading the file with the Read tool. Do not reconstruct from memory.
  2. Accuracy of change amount: git diff --stat Use the results directly. Do not estimate.
  3. Commit hash accuracy: git rev-parse --short Use the results.
  4. Line number accuracy: Use the actual line numbers of the file read with the Read tool.
  5. Do not omit "why": Every file and change block must include a "why" explanation.
  6. Do not omit files: In diff mode, every changed file must be described. In flow mode, every key file in the call chain must be included.