comment-code

Adds and enhances comments and documentation comments in code. The goal is to document role boundaries, caller prerequisites, return value contracts, and dependencies with other components in a 'readable on the spot' format without modifying code implementation.

Usage

comment-code <target file or directory> [--lang <language>]

If no arguments are provided, the diff files from

git diff HEAD

will be targeted. When

--lang

is specified, the documentation comment format (JSDoc / docstring / rustdoc, etc.) will be treated as the priority language. If not specified, it will be automatically determined from the file extension.

Prerequisites

The target files must be readable
Must be within a Git repository (since
```
git diff HEAD
```
is used when arguments are omitted)

Flow

Step 1: Identify target files

If arguments are specified, those files/directories will be targeted.

bash

# Without arguments: List recent diff files (compare both staged/unstaged with HEAD)
git diff HEAD --name-only
# To include untracked (new uncommitted) files
git ls-files --others --exclude-standard

If the target is empty (no changes / no arguments), confirm the target with the user.

Step 2: Investigate the role of the target in the codebase

This step is the most important. Don't just look at individual files; understand their position in the overall system.

2-1: Investigate callers

Search the entire codebase for symbols (functions, classes, types, constants) exposed by the target file to understand which layers/services call them.

bash

# Search for callers by symbol name (e.g., exported function name)
grep -rn "target symbol name" --include="*.ts" --include="*.js" .

2-2: Check imports and dependencies

Understand external modules, services, and configurations that the target file depends on.

bash

# List import statements
grep -n "^import\|^from\|require(" target-file

2-3: Check package/service boundaries

Confirm package names and public APIs using
```
package.json
```
,
```
go.mod
```
,
```
Cargo.toml
```
, etc.
If inter-service communication (HTTP clients, event publishing, message queues) is involved, identify the connection destination.
Check the relationship between the target and authentication/authorization middleware or session management.

2-4: Check existing comment styles

Read existing comments in the same file/package to understand the style (JSDoc / docstring / rustdoc, etc.) and language (Japanese/English).

Step 3: Add and enhance comments

Write comments incorporating the "perspective from other files/services" identified in Step 2.

Comment Style Guidelines (Core Principles)

.claude/rules/code-comment-style.md

exists in the target repository, follow it first. If not, follow the key points below.

Content to include:

Aspect	Content to write
Role/responsibility boundaries	"This module handles the boundary of ~ service", "Functions as the public interface of ~ package"
Caller context	Which layers/services call it. The state/permissions assumed by the caller
Contract with callee	What is guaranteed to be returned. Conditions and meanings of errors/exceptions (whether to return null or throw an exception, etc.)
Dependencies with other files/services	External dependencies, configurations, shared states that cannot be found without cross-referencing files
Non-obvious constraints/background/why	Why the implementation is structured this way. Background, context, and specification limitations

Content to avoid:

Verbose explanations that are obvious from the signature/type (paraphrasing "what")
Duplicate information that easily becomes outdated and diverges from the implementation
Comments that only document resolved context

Documentation Comments (Language-Specific Conventions)

Use formats that follow language conventions:

TypeScript / JavaScript: JSDoc (
```
/** ... */
```
)
Python: docstring (
```
"""..."""
```
)
Rust:
```
///
```
(items) /
```
//!
```
(modules)
Go:
```
// FuncName ...
```
format
Java / Kotlin: Javadoc (
```
/** ... */
```
)
Others: Follow the conventions in the official language documentation

Write the "role/boundary" in the opening summary line, and add caller/callee context and non-obvious constraints in the body.

Inline Comments

Write the "why" (why the implementation is this way). The "what" is indicated by the code. Constraints, background, and specification considerations should be written immediately before the relevant line or block. Actively include references to external information (Issue numbers, specification document URLs).

Good/Bad Examples

Bad example (verbose paraphrasing of "what"):

typescript

/**
 * Receives a user ID and returns user information.
 * @param userId User ID
 * @returns User information
 */
function getUser(userId: string): User | null { ... }

Good example (includes role and perspective from other components):

typescript

/**
 * Public interface of the authentication layer. Called from API handlers,
 * assuming only calls with validated sessions (unauthenticated requests are blocked by upstream middleware).
 *
 * Delegates to UserRepository and returns values retrieved from the DB.
 * Returns null if the user does not exist (does not throw exceptions)——
 * Callers must perform null checks.
 *
 * Note: Soft-deleted users are also treated as null (specification: issue #142).
 */
function getUser(userId: string): User | null { ... }

Step 4: Perform self-check

Review the added/enhanced comments from the following perspectives.

Content Accuracy

Is it not a verbose paraphrase of obvious content from the signature/type?
Is there no content that diverges from the implementation (does it not contradict the signature)?
Are the investigation results from Step 2 (callers, dependencies) correctly reflected in the comments?

Security (Mandatory Check)

Are secrets such as API keys, tokens, or passwords not written in comments?
Is personal identifiable information (PII) not directly included in comments (e.g., user ID examples)?
Are authentication/authorization prerequisites not described in a misleading way (e.g., incorrect "no authentication required" statements)?
Are security constraints and permission prerequisites clearly and accurately described?

If issues are found in the above checks, modify the comment content before proceeding.

Japanese Style

Is it written in plain form (da/dearu style)?
Are commands, identifiers, and filenames kept in English (not translated)?
Is there no excessive use of emojis?

Step 5: Present diff and report

Present changes in diff format and report in the following format.

## comment-code Completion Report

### Target Files
- `path/to/file.ts` (Added: N, Enhanced: M)

### Perspectives of Added Comments
- Caller: [Location where caller information is specified]
- Contract with callee: [Location where return value/error conditions are specified]
- Non-obvious constraints/background: [Location where "why" is described]

### Security Check
- Result: ✅ No issues / ⚠️ Warnings (details)

### Next Actions
- To commit: Use the create-commit skill
- To update CLAUDE.md: Use the update-docs skill

Commit is delegated to the

create-commit

skill (this skill itself does not perform commits).

Verification

After adding comments, verify with the following.

bash

git diff HEAD

Ensure code logic (function bodies, control flow) has not been modified
Ensure added comments do not contradict the implementation
Ensure all items in the Step 4 self-check list have been passed

Common Failures

Issue	Mitigation
Writing verbose content that is obvious from the signature/type (paraphrasing "what")	Only write non-obvious information such as "why the implementation is this way" or "caller prerequisites"
Writing comments based on speculation without investigating callers	Always confirm callers using grep in Step 2 before writing
Including secrets/PII in comments	Confirm no secrets/PII exist during the Step 4 security check
Modifying code logic while "organizing"	Leave a TODO comment where implementation changes are needed and redirect to `implement-issue`

Notes

Do not modify code logic — Only add or enhance comments. If implementation issues are identified, redirect to the
```
implement-issue
```
skill
Keep comments synchronized with implementation — If existing comments diverge from the implementation, correct them (outdated comments are more harmful than accurate ones)
Follow detailed rules of the target repository — If
```
.claude/rules/code-comment-style.md
```
exists, prioritize it. The key points in Step 3 of this skill serve as a fallback when that file is not available
Assume AI agents are also readers — Assume "you can find it by referencing other files" does not apply. Agents like Claude use comments as their primary context source
Avoid bypassing pre-commit hooks with
```
--no-verify
```
. If hooks fail during commit, investigate and fix the cause before re-running

comment-code

NPX Install

Tags

SKILL.md Content (Chinese)

comment-code

Usage

Prerequisites

Flow

Step 1: Identify target files

Step 2: Investigate the role of the target in the codebase

2-1: Investigate callers

2-2: Check imports and dependencies

2-3: Check package/service boundaries

2-4: Check existing comment styles

Step 3: Add and enhance comments

Comment Style Guidelines (Core Principles)

Documentation Comments (Language-Specific Conventions)

Inline Comments

Good/Bad Examples

Step 4: Perform self-check

Content Accuracy

Security (Mandatory Check)

Japanese Style

Step 5: Present diff and report

Verification

Common Failures

Notes