Rokcso's Blog

Tax Filing for Non-Resident's US LLC: Form 5472 Filing Guide

hi@rokcso.com (rokcso) — Thu, 19 Mar 2026 12:00:00 +0800

The previous article shared How to Fill Out Form 1120. Now, let’s continue with filling out Form 5472, primarily based on the Instructions for Form 5472 released by the IRS.

To reiterate, Form 5472 is an information return used to report “reportable transactions” between foreign persons and U.S. companies to the IRS. The key point here is “reportable transactions.” So, who is a related party? In common cases, it mainly refers to the foreign owner of this U.S. company. For other situations, please refer to the official instructions.

Therefore, the first step in Form 5472 is to clearly fill in the company information, owner information, and related party information. This typically includes:

Basic company information, such as name, address, EIN, etc. (Part I)
Information on 25% foreign shareholders (Part II)
Related party information (Part II)

Next, clearly fill in the reportable transaction information that occurred with the related party. So, which transactions need to be reported? They usually include:

Monetary transactions (Part IV)
Transactions specific to a Foreign-owned U.S. DE, such as contributions, distributions, etc. (Part V)
Non-monetary transactions (Part VI)

Filling Instructions

Reference for filling the first page:

Explanations for some items:

Part I

This section mainly fills in basic company information.

At red dot 1, fill in the company’s tax year. If it’s the company’s first year of existence, the period is from the company’s formation date to December 31 of that year; otherwise, it’s from January 1 to December 31 of the year.

At red dot 6 (i.e., Part I 1c), fill in the company’s total assets. If item D on Form 1120 is not left blank, the total assets figure here should match the value in item D of Form 1120.

At red dots 7 and 8 (i.e., Part I 1d, 1e), fill in the company’s business and its code. They can be looked up on NAICS Association.

At red dot 9 (i.e., Part I 1f), fill in the sum of transaction amounts between the company and the current related party. This should equal the total sum of transaction amounts from Part IV + Part V + Part VI later. In 2025, my company had not generated any monetary or non-monetary income or expenses, only the costs of company formation needed to be reported.

At red dot 11 (i.e., Part I 1h), fill in the sum of transaction amounts between the company and all related parties.

Note: The IRS requires a separate Form 5472 for each related party associated with the company. If the company has multiple related parties, then Part I 1h should equal the sum of the Part I 1f values from all related parties’ Form 5472s.

At red dot 10 (i.e., Part I 1g), fill in the number of Form 5472s being filed for the year. For my company, the only related party is myself, so I fill in 1.

At red dot 12 (i.e., Part I 1j), check this box if it is the company’s first year filing Form 5472.

At red dot 13 (i.e., Part I 1k), fill in 0 or leave it blank if there is no cost sharing arrangement (Part VIII).

At red dot 16 (i.e., Part I 1n), literally refers to the country where the company files its tax return as a resident. After discussion with my CPA, since my SMLLC is a tax pass-through entity to me as an individual, and I file my personal tax return as a resident in China, so I fill in China here.

At red dot 17 (i.e., Part I 1o), literally refers to the country where the company conducts its principal business activities. Although my company’s business targets global users, I personally mainly work on the company’s business operations in China, so I fill in China here.

Part II

This section mainly fills in basic shareholder information.

At red dot 21 (i.e., Part II 4b(1)), the shareholder’s SSN or ITIN. If none, it can be left blank directly. My CPA suggested I could write FOREIGN-US for clarity.

At red dot 22 (i.e., Part II 4b(2)), a company-defined reference number used to identify the shareholder. It can be customized by the company, as long as it follows IRS rules (combination of letters and numbers, within 50 characters). Note that this custom reference number for the shareholder must remain consistent in subsequent years.

I personally use the name concatenated with the company EIN, removing special characters, with all letters capitalized.

At red dot 23 (i.e., Part II 4b(3)), the shareholder’s foreign taxpayer identification number. For me, this is the Chinese taxpayer identification number, i.e., the ID card number.

Reference for filling the second page:

Explanations for some items:

Part III

This section mainly fills in related party information. Part III of one Form 5472 can only contain information for one related party.

At red dot 8 (i.e., Part III 8e), select the type of related party. Selecting “25% foreign shareholder” indicates the related party is a 25% foreign shareholder of the company.

Part IV

Monetary transactions between the related party and the company. If none, fill all with 0 or leave blank.

Part V

At red dot 11, check this box if the related party engaged in the specific transactions listed in this part (e.g., contributions, distributions) with the company. Additionally, a separate statement detailing the transactions must be attached to the back of Form 5472.

The costs of company formation need to be reported in this part. There is no fixed format required for the attached separate statement; you can have AI write it, for example:

Part VI

Non-monetary transactions between the related party and the company. If none, do not check the box.

Reference for filling the third page:

Explanations for some items:

Part VII

This section mainly provides additional information. Typically, you can check the boxes as shown in the image.

Part VIII

Regarding cost sharing agreements, most likely there are none (corresponding to Part I 1k). You can leave it blank, or fill it as shown in the image.

Part IX

Regarding BEAT, most likely there is none. You can leave it blank, or fill it as shown in the image.

Submission

Finally, merge the completed Form 1120, Form 5472, and explanatory attachments into a single PDF in order, and fax it to +1 855-887-7737.

Note: It’s best to keep the fax transmission receipt permanently, along with other company-related documents.

非美国居民的 US LLC 税务申报：Form 5472 填写指南

hi@rokcso.com (rokcso) — Thu, 19 Mar 2026 10:00:00 +0800

🔄 English

前一篇分享了 Form 1120 如何填写，现在继续填写 Form 5472，主要参考 IRS 发布的 Form 5472 填写说明。

再次解释一下 Form 5472 是用来向 IRS 报告外国人与美国公司之间的「关联方交易」的信息申报表，这里的重点是「关联方交易」，那么谁是关联方？常见情况主要是指这个美国公司的外国所有者，其他情况可以参考官方说明。

所以在 Form 5472 中首先要填写清楚公司信息以及所有者信息以及其关联方信息，通常包括：

公司基本信息，如名称、地址、EIN 等（Part I）
25% 外国股东信息（Part II）
关联方信息（Part II）

然后再填写清楚和关联方产生的需要申报的交易信息，那么哪些交易是需要申报的？通常包括：

货币交易（Part IV）
Foreign-owned U.S. DE 特有的交易，如注资、分配等（Part V）
非货币交易（Part VI）

填写说明

第一页填写参考：

部分填写项解释：

Part I

这一部分主要填写公司基本信息。

红点 1 处，填写公司税务周期，如果当年是公司成立首年，则从公司成立日期到当年 12 月 31 日，否则从当年 1 月 1 日到 12 月 31 日。

红点 6 处（即 Part I 1c），填写公司总资产，如果 Form 1120 的 D 项没有留空，那么此处的总资产数额要和 Form 1120 的 D 项的值可以对上。

红点 7、8 处（即 Part I 1d、1e），填写公司业务及其代码，可以在 NAICS Association 查询。

红点 9 处（即 Part I 1f），填写公司与当前关联方交易额之和，需要等于后面 Part IV + Part V + Part VI 交易金额的总和。2025 年我的公司还没有产生任何货币或非货币的收入、支出，只有公司成立的费用需要申报。

红点 11 处（即 Part I 1h），填写公司与所有关联方交易额之和。

注意：IRS 要求与公司相关的每一个关联方都需要单独填写一份 Form 5472, 如果公司存在多个关联方，那么 Part I 1h 要等于所有关联方的 Form 5472 的 Part I 1f 的数值之和。

红点 10 处（即 Part I 1g），填写本年度提交的 Form 5472 的数量，我的公司的关联方只有我一个，所以填写 1。

红点 12 处（即 Part I 1j），如果当年是公司首年提交 Form 5472，则需要勾选。

红点 13 处（即 Part I 1k），没有成本分摊（Part VIII）就填写 0 或者留空。

红点 16 处（即 Part I 1n），字面意思是指公司作为居民报税的国家，我和我的 CPA 讨论的结果是，我的 SMLLC 税务穿透到个人，而我个人在中国作为居民报税，所以这里填写 China。

红点 17 处（即 Part I 1o），字面意思是指公司主要开展业务的国家，虽然我的公司业务面向全球用户，但是我个人是主要在中国为公司业务运营开展工作，所以这里填写 China。

Part II

这一部分主要填写公司股东基本信息。

红点 21 处（即 Part II 4b(1)），股东的 SSN 或者 ITIN，没有可以直接留空，我的 CPA 建议我可以填写 FOREIGN-US 更明确一点。

红点 22 处（即 Part II 4b(2)），公司自定义的用来识别该股东的参考号码，由公司自己自定义，只要符合 IRS 的规则（字母和数字组合，50 字符以内）即可，需要注意之后每年该股东的自定义参考号码都要保持一致。

我个人习惯用名字拼接公司 EIN，去除特殊符号，字母全大写。

红点 23 处（即 Part II 4b(3)），股东的外国纳税人识别号，对于我来说就是中国的纳税人识别号，即身份证号码。

第二页填写参考：

部分填写项解释：

Part III

这一部分主要填写关联方信息，一份 Form 5472 的 Part III 只能填写一个关联方信息。

红点 8 处（即 Part III 8e），选择关联方的类型，选择 25% foreign shareholder 表示关联方就是公司 25% 外国人股东。

Part IV

关联方与公司的货币交易，如果没有就全填写 0 或者留空。

Part V

红点 11 处，如果关联方与公司存在这部分注明的特有交易（如注资、分配等）则勾选，并且需要另外在 Form 5472 后面附上一份单独的说明，说明交易详情。

而公司成立的费用就需要在这部分申报。需要附上的单独说明没有固定格式要求，可以让 AI 写，比如：

Part VI

关联方与公司的非货币交易，如果没有就不勾选。

第三页填写参考：

部分填写项解释：

Part VII

这一部分主要填写一些附加信息，通常直接如图勾选即可。

Part VIII

关于成本分摊协议，基本都没有（对应 Part I 1k），可直接留空，或者如图填写。

Part IX

关于 BEAT，基本都没有，可直接留空，或者如图填写。

提交

最终将填写好的 Form 1120、Form 5472 以及说明附件按顺序拼接到一个 PDF，传真给 +1 855-887-7737 即可。

注意最好将传真回执和公司相关文件一样永久保留。

Building Shipstry: 640 Commits, 9 Days, One Launch

hi@rokcso.com (rokcso) — Fri, 13 Mar 2026 10:00:00 +0800

On March 3, 2026, I started with an empty folder. On March 11, 2026, Shipstry went live.

In between: 640 commits, countless cups of coffee, and a lot of lessons learned about building on the edge.

This is the story of how I built it, the technical decisions I made, and what I learned along the way.

Shipstry.com

The Name

Before writing a single line of code, I needed a name.

I spent an entire afternoon brainstorming with AI. I must have asked for hundreds of suggestions. The AI probably hated me by the end of it.

I wanted something that captured the essence of what makers do — we ship products. And I wanted it to feel like a registry, a place where products are officially recorded and discovered.

Ship + Registry = Shipstry

It sounded nautical, it felt right, and the .com was available. Done.

The nautical theme evolved into something more organic:

Primary color: Olive Moss (#6B8A67)
Accent: Warm Sand (#D4A574)
Pricing tiers: Harbor, Voyage, Expedition, Admiral
The logo: a geometric sailboat with twin sails

The Why

After launching several side projects over the years, I kept running into the same problem: Product Hunt is great, but it’s not built for indie makers anymore.

Big-budget launches dominate. Marketing teams game the algorithm. Great products from solo developers get buried in hours.

I wanted something different:

A place that celebrates builders, not marketers
Weekly cycles instead of daily chaos
Quality over quantity
Built by a maker, for makers

So I built Shipstry — “The Launch Registry.”

The Stack Decision

Before writing code, I spent time on stack selection. This is the most important decision you make at the start of a project — it will haunt you for months if you get it wrong.

I chose:

TanStack Start for the framework. It’s a full-stack React framework with file-based routing and excellent TypeScript support. The type safety is incredible — if you change a route, the compiler tells you everywhere that needs updating.

Cloudflare Workers for deployment. Edge computing means my users in Singapore, London, and New York all get the same fast experience. No cold starts, global distribution.

Cloudflare D1 for the database. It’s SQLite at the edge. Yes, SQLite — the same database that powers your phone, now running in 300+ locations worldwide. For a product like Shipstry, it’s perfect.

Cloudflare R2 for file storage. When users upload product logos and preview images, they go here. It’s S3-compatible but with zero egress fees, which means I don’t have to worry about surprise bandwidth bills.

Better Auth for authentication. Email/password plus Google OAuth, and it integrates natively with TanStack Start.

Stripe for payments, Resend for emails, Tailwind CSS v4 for styling, shadcn/ui for components.

The key insight: TanStack Start + Cloudflare is a powerful combination. You get React’s ecosystem with edge performance, and D1 gives you a real database with zero configuration.

The First Week

Day 1-2: Foundation

The first commits set up the entire foundation — TanStack Start with SSR, Cloudflare Workers adapter, Drizzle ORM, basic routing structure.

I also built the design system. I didn’t want another generic AI landing page with purple gradients. I created a custom “Olive Moss” palette — muted greens and warm grays that feel organic and calm.

By end of Day 2, I had a working dev server, a distinctive visual identity, and basic page layouts.

Day 3-4: Authentication

Authentication is always more complicated than you expect.

Better Auth needs to create its auth instance per-request, not as a singleton. In Cloudflare Workers, each request is isolated anyway, so this architecture actually works well. But figuring that out took a few hours of head-scratching.

I also designed the database schema upfront. The key decision: separating drafts from products.

Drafts have all nullable fields — users can save at any point in the submission flow and return later. Products have required fields — they only exist when fully submitted. This kept the data model clean and the code simple.

Day 4-5: The Submission Flow

The submission form is the heart of Shipstry. I wanted it to feel smooth, not overwhelming.

I built a progressive form with collapsible sections. Each section tracks its completion status. Users can save at any point, leave, and pick up where they left off days later.

For the product description, I integrated Milkdown — a plugin-driven Markdown editor with a custom toolbar. The tricky part was focus management: the toolbar kept stealing focus from the editor. I eventually fixed it by preventing default on mousedown for toolbar buttons.

Day 5: Pricing and Payments

I designed a nautical-themed pricing system:

Harbor (Free): Basic submission, normal review
Voyage ($9.9): Fast 24-hour review, same-week ship
Expedition ($29): Featured on homepage, 7 days exposure
Admiral ($59): 30 days featured, premium badge

Stripe integration was straightforward, but the webhook handler needed careful attention. D1 doesn’t support nested transactions, so I had to restructure the code to use sequential queries instead of wrapping everything in a transaction.

The AI Feature

Filling out product forms is tedious. Users paste a URL and then have to manually enter the name, tagline, description, logo, preview image…

So I built an AI-powered metadata fetcher.

✨ AI Stow…

When a user pastes their product URL, the system:

Fetches the page and extracts Open Graph tags
Sends the information to AI to generate an enhanced, compelling description
Auto-fills all the form fields

The user can review and edit everything before submitting. It’s not about replacing human input — it’s about reducing friction.

Multi-Provider Failover

AI APIs are unreliable. They timeout, they rate limit, they have outages.

I built a failover system that tries multiple AI providers in priority order. If one fails, it automatically tries the next. The configuration is a simple JSON array in environment variables:

[
  {"name": "openai", "priority": 1},
  {"name": "claude", "priority": 2},
  {"name": "gemini", "priority": 3}
]

If all providers fail, the form still works — users just fill it manually. Graceful degradation is key.

SSRF Protection

Allowing users to fetch arbitrary URLs is dangerous. You don’t want someone hitting your internal services through your server.

I implemented multiple layers of protection:

Block private IP ranges (10.x, 172.x, 192.168.x)
Block localhost
Only allow HTTP and HTTPS protocols
Rate limit: 5 requests per minute per user

The Community Features

Comments and Voting

Comments support nesting — users can reply to replies. I used soft deletes instead of hard deletes, so if a parent comment is removed, the threading structure stays intact.

For voting, I wanted instant feedback. Nobody wants to wait for a server round-trip to see their vote register.

I implemented optimistic updates: when you click vote, the UI updates immediately. The server request happens in the background. If it fails, the UI rolls back. This makes the app feel snappy and responsive.

Notifications

Users get notified for:

Comments on their products
Replies to their comments
Award wins (weekly and monthly)
Product status changes (approved, rejected)

For email delivery, I used Cloudflare’s waitUntil() function. This sends the response to the user immediately while the email sends in the background. The user doesn’t wait for the email to send.

The Final Days

Caching

To reduce database load, I built a caching layer using D1 itself as the cache store. Cached data has TTLs, and mutations trigger automatic cache invalidation.

This pattern dramatically reduced read load on the main tables during high-traffic periods.

Environment Configuration

I centralized all environment variables with validation. In development, the app validates that all required secrets exist and throws clear errors if something is missing. In production, I trust that Cloudflare has the secrets configured.

This caught several configuration mistakes during development that would have been painful to debug in production.

Launch

On March 11, 2026, Shipstry went live.

The final commits added a launch promo banner with a 50% discount code, and adjusted the ship week logic to allow immediate launches during the launch period.

What I Learned

TanStack Start is ready for production. The framework is stable, well-typed, and SSR works seamlessly with Cloudflare Workers.

D1 is good enough. SQLite at the edge sounds limiting, but for most applications, it’s perfect. Zero configuration, fast queries, generous free tier. The main gotcha is no nested transactions.

Edge functions change how you think. No global state, waitUntil() for background tasks, zero cold starts, environment access through imports rather than process.env.

AI integration is easier than expected. With the right abstraction — multi-provider failover and graceful degradation — you can build reliable AI features.

640 commits in 9 days. That’s roughly 71 commits per day. Each commit was small, focused, and reversible. The discipline of atomic commits saved me multiple times when I needed to roll back a bad decision.

What Happened After Launch

Shipstry has been live for two days.

In that time, I’ve been doing link building — submitting to directories, reaching out to communities, getting featured on various platforms.

The results? DR went from 0 to 14 in two days.

Try It

Shipstry: shipstry.com
Submit your product: shipstry.com/submit
Launch promo: Use code SHIPSTRY50 for 50% off paid plans

Built with TanStack Start, Cloudflare Workers, D1, R2, and too much coffee.

Tax Filing for Non-Resident's US LLC: Form 1120 Filing Guide

hi@rokcso.com (rokcso) — Mon, 09 Mar 2026 12:00:00 +0800

🔄 简体中文

Through prior research and study, I have largely understood the U.S. LLC Tax Terms for Non-Residents and clarified that for my current Foreign-owned U.S. SMLLC, the tax filing requires submitting two forms to the IRS: Form 1120 and Form 5472.

Essentially, the requirement is to submit Form 5472, and Form 5472 must be filed together with Form 1120 to the IRS; therefore, Form 1120 merely needs to be filled out with basic information as a formality. However, the filing deadline typically falls on April 15th each year.

Filling Instructions

It is recommended to check the IRS official guidelines annually for any updates to the filing requirements. This article was last updated in March 2026.

First, the Instructions for Form 1120 clearly state:

Foreign-owned domestic disregarded entities. If a foreign person, including a foreign corporation, wholly owns a domestic disregarded entity (DE), the domestic DE is treated as a domestic corporation separate from its owner (the foreign corporation) for the limited purposes of the requirements under section 6038A that apply to 25% foreign-owned domestic corporations. While a DE is not required to file a U.S. income tax return, a DE covered by these rules is required to file a pro forma Form 1120 with Form 5472 attached by the due date (including extensions) of the return. See the Instructions for Form 5472 for additional information and coordination with Form 5472 reporting by the domestic DE.

This means a Foreign-owned U.S. DE must file a pro forma Form 1120, with Form 5472 attached, by the due date (including extensions) of Form 1120. For specific filling instructions, refer to the Instructions for Form 5472.

The Instructions for Form 5472 explicitly state:

When and Where To File

File Form 5472 as an attachment to the reporting corporation's income tax return by the due date (including extensions) of that return.

Foreign-owned U.S. DEs. While a foreign-owned U.S. DE has no income tax return filing requirement, as a result of final regulations under section 6038A, it will now be required to file a pro forma Form 1120, U.S. Corporation Income Tax Return, with Form 5472 attached by the due date (including extensions) of that Form 1120. The only information required to be completed on Form 1120 is the name and address of the foreign-owned U.S. DE and items B and E on the first page. The foreign-owned U.S. DE has the same tax year used by its owner for U.S. tax filing requirements or, if none, the calendar year.

Dedicated mailing address. Foreign-owned U.S. DEs are required to use the following dedicated mailing address. These filers do not use the mailing address provided in the Instructions for Form 1120.

Note. “Foreign-owned U.S. DE” should be written across the top of the Form 1120. File these forms by:

- Fax (300 DPI or higher) to 855-887-7737, or
- Mail to:

Internal Revenue Service
1973 Rulon White Blvd
M/S 6112 Attn: PIN Unit
Ogden, UT 84201

This reiterates that a Foreign-owned U.S. DE must file a pro forma Form 1120, with Form 5472 attached, by the due date (including extensions) of Form 1120.

On Form 1120, only the following needs to be filled:

Write “Foreign-owned U.S. DE” across the top of Form 1120.
Company name and address (consistent with company registration documents, EIN application materials, etc.)
Item B (EIN)
Item E (check as applicable)
Signature at the bottom of page 1 (name, date, title) still needs to be provided.

Note: Item E only needs to be checked the first time and the last time you file Form 1120. Leave all other pages completely blank.

Additional note: Foreign-owned U.S. DEs must use the dedicated mailing address when submitting Form 1120 (with Form 5472 attached), not the mailing address provided in the Instructions for Form 1120.

Dedicated address: By fax (300 DPI or higher resolution) to +1 855-887-7737 (mailing is not recommended).

Practical Guide

The above outlines the required content based on IRS official instructions. However, I have also consulted with a CPA. While filling as described is compliant, in practice, it might be advisable to include some additional information to ensure the IRS can review Form 1120 more clearly. Typically, the following may be added:

Tax period at the top
Item C, Date business started
Item D, Total assets (0 or leave blank)

Note for the tax period at the top: If this is the company’s first-year tax filing, enter the period from the company’s formation date to December 31 of that year (i.e., a short tax year). Otherwise, enter January 1 to December 31 of the current year, or leave it blank.

Finally, in the documents submitted to the IRS, it is acceptable to retain only the first page of Form 1120.

Example Reference

Red marks indicate required fields (except red mark 10), green marks indicate optional fields.

Note: The final package submitted to the IRS must also have Form 5472 attached after this Form 1120. Combine both into a single file and fax it in one go to the IRS.

Continue reading: Form 5472 Filling Guide.

非美国居民的 US LLC 税务申报：Form 1120 填写指南

hi@rokcso.com (rokcso) — Mon, 09 Mar 2026 10:00:00 +0800

🔄 English

经过之前的调研学习，大致弄清除了美国 LLC 报税名词，也搞清楚了给我目前这个 Foreign-owned U.S. SMLLC 进行税务申报需要向 IRS 提交 Form 1120 和 Form 5472 两张表格。

其实本质上是要提交 Form 5472，而 Form 5472 要求必须随 Form 1120 一同提交给 IRS，所以 Form 1120 只是形式上填写一下基本信息即可。但是提交截止时间通常都是每年 4 月 15 日。

填写说明

建议每年都检查一下 IRS 官方对于填写要求是否有更新，本文最后更新为 2026-03。

首先在 Form 1120 的填写说明中明确写到：

Foreign-owned domestic disregarded entities. If a foreign person, including a foreign corporation, wholly owns a domestic disregarded entity (DE), the domestic DE is treated as a domestic corporation separate from its owner (the foreign corporation) for the limited purposes of the requirements under section 6038A that apply to 25% foreign-owned domestic corporations. While a DE is not required to file a U.S. income tax return, a DE covered by these rules is required to file a pro forma Form 1120 with Form 5472 attached by the due date (including extensions) of the return. See the Instructions for Form 5472 for additional information and coordination with Form 5472 reporting by the domestic DE.

即 Foreign-owned U.S. DE 必须在 Form 1120 的到期日（包括延期）前提交一份形式上的 Form 1120，并附上 Form 5472。具体如何填写可以参阅 Form 5472 的说明。

而在 Form 5472 的填写说明中明确写到：

When and Where To File

File Form 5472 as an attachment to the reporting corporation's income tax return by the due date (including extensions) of that return.

Foreign-owned U.S. DEs. While a foreign-owned U.S. DE has no income tax return filing requirement, as a result of final regulations under section 6038A, it will now be required to file a pro forma Form 1120, U.S. Corporation Income Tax Return, with Form 5472 attached by the due date (including extensions) of that Form 1120. The only information required to be completed on Form 1120 is the name and address of the foreign-owned U.S. DE and items B and E on the first page. The foreign-owned U.S. DE has the same tax year used by its owner for U.S. tax filing requirements or, if none, the calendar year.

Dedicated mailing address. Foreign-owned U.S. DEs are required to use the following dedicated mailing address. These filers do not use the mailing address provided in the Instructions for Form 1120.

Note. “Foreign-owned U.S. DE” should be written across the top of the Form 1120. File these forms by:

- Fax (300 DPI or higher) to 855-887-7737, or
- Mail to:

Internal Revenue Service
1973 Rulon White Blvd
M/S 6112 Attn: PIN Unit
Ogden, UT 84201

即 Foreign-owned U.S. DE 必须在 Form 1120 的到期日（包括延期）前提交一份形式上的 Form 1120，并附上 Form 5472。

而 Form 1120 上仅需填写：

在 Form 1120 顶部注明「Foreign-owned U.S. DE」
公司名称和地址（和公司注册文件、EIN 申请材料等保持一致）
B 项（EIN）
E 项（视情况勾选）
第一页底部的签名（姓名、日期、职位）还是需要签署一下

注意 E 项只需要在第一次和最后一次提交 Form 1120 时需要勾选。其余页面全部留空即可。

另外注意：Foreign-owned U.S. DE 提交 Form 1120（附 Form 5472）的地址必须使用专用邮寄地址，不得使用 Form 1120 填写说明中提供的邮寄地址。

专用邮寄地址：传真（300 DPI 或更高分辨率）至 +1 855-887-7737（邮寄方式不推荐）。

实操指南

以上为根据 IRS 官方介绍要求填写的内容，不过我也咨询过 CPA，按照以上要求填写是符合要求的，但是实操过程中可能会多填一些内容，保证 IRS 在审阅 Form 1120 的时候可以更明确。通常会额外填写：

顶部的税务周期
C 项公司成立日期
D 项公司总资产（0 或留空）

注意顶部的税务周期，如果当前是公司首年报税，填写公司成立日期到当年 12 月 31 日（即短税务年），否则填写当年 1 月 1 日到 12 月 31 日或者留空。

并且最终提交给 IRS 的文件中，Form 1120 只保留第一页是可以的。

示例参考

红色标记为必填（红 10 除外），绿色标记为可选。

注意：最终要提交给 IRS 的文件还需要在当前这个 Form 1120 的后面附上 Form 5472, 将两者合并为一个文件后一次性传真给 IRS。

继续参考：Form 5472 的填写指南。

Tax Terms Explanation for US LLC: Tax Basics for Independent Developers

hi@rokcso.com (rokcso) — Fri, 06 Mar 2026 12:00:00 +0800

🔄 简体中文

What forms must a SMLLC owned by a non-U.S. resident submit for IRS tax filings?

⚠️ Note:

The following explanations of terms are not 100% complete or comprehensive. True completeness might only be found by delving into the tax code. I will omit some information or exceptions that I personally consider relatively unimportant for my current situation regarding the “Tax Filing for a Foreign-owned U.S. DE,” such as the fact that there are more variations of Form 1040 than those mentioned below, or that not all foreign citizens need to undergo the Substantial Presence Test when determining NRA status, etc.
Furthermore, considering the contents of the U.S.-China Income Tax Treaty, the situation could become much more complex, to the point where I’m having a bit of trouble figuring it out… so I’ll skip that for now. I’ll research how to use the U.S.-China Income Tax Treaty to claim exemption from taxes only if/when I am actually deemed to have a USTB, have ECI, and need to pay taxes in the U.S. (There’s a good chance this won’t happen).

Glossary

Disregarded entity (DE)

An entity that, for U.S. federal income tax purposes, is not considered separate from its owner.

General Principle: As a DE, its income and expenses are “passed through” to its owner for U.S. income tax purposes. In theory, the owner can simply report this on their individual income tax return (using Form 1040).

Key Exception: Pursuant to the requirements of Internal Revenue Code Section 6038A, a Foreign-owned U.S. DE is treated as a separate corporation for specific reporting obligations. Therefore, a Foreign-owned U.S. DE must file a corporate income tax return (Form 1120) and must attach Form 5472.

Foreign-owned U.S. DE

Foreign-owned U.S. Disregarded Entity. Refers to a U.S. domestic disregarded entity that is wholly owned by a foreign individual.

A Wyoming SMLLC wholly owned by a non-U.S. tax resident individual is a typical example of a Foreign-owned U.S. DE.

NRA

Stands for Nonresident Alien, a concept in U.S. tax law used to define an individual’s tax status, specifically referring to foreign citizens who do not meet the criteria for U.S. tax residency.

The determination is based on the reverse outcome of the following two tests (i.e., failing both tests results in NRA status):

Green Card Test: Fails the test if the individual was not a U.S. lawful permanent resident (i.e., did not hold a green card) at any time during the tax year.
Substantial Presence Test: Fails the test if the individual does not meet either of the following conditions during the tax year:
- Was present in the U.S. for more than 31 days in the current year, and
- The sum of the following formula exceeds 183 days:
  (Days present in current year + Days present in prior year / 3 + Days present in second prior year / 6) > 183

ECI

Stands for Effectively Connected Income, which refers to income that is from U.S. sources and is directly connected to the conduct of a trade or business within the United States by a non-U.S. resident taxpayer.

Core Determination Logic: First, determine if a U.S. Trade or Business (USTB) exists. Then, identify which U.S. source income is effectively connected to that business.

If there is ECI, federal income tax must be paid. Individuals file Form 1040, and corporations file Form 1120. However, since an SMLLC is a DE, its income “passes through” to the individual, so the individual would need to file Form 1040 (or a variant).

But the company also has an independent filing obligation at the corporate level: to file Form 1120. If the SMLLC is owned by an NRA, it needs to file a pro forma Form 1120 and attach Form 5472.

Form 1040

U.S. Individual Income Tax Return. It is the form that the IRS requires eligible taxpayers to file annually to report their federal individual income tax.

Primarily used by U.S. tax residents, including U.S. citizens, green card holders, and foreigners deemed residents under the “Substantial Presence Test” (non-NRAs).

In addition to the standard Form 1040, there is a series of variants:

Form 1040-SR: An optional form designed for taxpayers aged 65 and older.
Form 1040-NR: Designed specifically for Nonresident Aliens to report their U.S. source income. When a nonresident alien has U.S. income, this form must be used instead of the standard Form 1040.
Form 1040-X: Used to amend a previously filed Form 1040, Form 1040-SR, or Form 1040-NR.

When filing Form 1040, various schedules are typically attached to provide additional detailed information, such as:

Schedule C: Used to report profit or loss from a sole proprietorship or single-member LLC.
Schedule A: Used to report itemized deductions, such as medical expenses, state taxes, mortgage interest, and charitable contributions.
Schedule B: Used to report interest and dividend income.
Schedule D: Used to report capital gains and losses.

Form 1120

Filing Reference: Tax Filing for Non-Resident’s US LLC: Form 1120 Filing Guide

U.S. Corporation Income Tax Return. It is the form that the IRS requires eligible corporate entities to file annually to report their federal corporate income tax.

Entities taxed as C corporations, or other entities that have elected to be taxed as C corporations by filing Form 8832, as well as U.S. disregarded entities owned by non-U.S. persons or entities (Foreign-owned U.S. DEs), are required to file Form 1120.

However, a Foreign-owned U.S. DE files Form 1120 not because the entity needs to pay income tax like a C corporation, but to fulfill its special information reporting obligation. The Form 1120 filed by a Foreign-owned U.S. DE is only Pro Forma in nature. It only requires basic information to be filled out; no financial data needs to be entered.

A Foreign-owned U.S. DE must attach Form 5472 when filing the Pro Forma Form 1120, to report its transactions with foreign related parties. In fact, this Pro Forma Form 1120 mainly serves as a “cover sheet” for Form 5472 to meet formal requirements. The real focus is Form 5472.

Form 5472

Filing Reference: Tax Filing for Non-Resident’s US LLC: Form 5472 Filing Guide

Information Return of a 25% Foreign-Owned U.S. Corporation or a Foreign Corporation Engaged in a U.S. Trade or Business. It is an information return that the IRS requires specific corporations to file.

It is not itself a tax return used to calculate and pay taxes; rather, it is a tool for the IRS to monitor and track cross-border related-party transactions. It must be filed even if the company has no income and no tax liability. Failure to file incurs a minimum penalty of $25,000 per occurrence.

Summary

We just need to analyze the tax filing along two separate but somewhat connected lines: the individual and the company.

First, for the individual: Since I am a Nonresident Alien (NRA) and have no ECI, I do not need to file an individual income tax return, i.e., I do not need to file Form 1040-NR.

Second, for my U.S. LLC: It is a Foreign-owned U.S. DE, so the corporate income tax “passes through” to the individual. In theory, the company doesn’t need to file a return; the individual does. But the individual is an NRA with no ECI, so the individual also doesn’t need to file.

However, due to the requirements of Internal Revenue Code Section 6038A, a Foreign-owned U.S. DE has special filing obligations, but these are simplified. It does not need to file a standard Form 1120, but rather a pro forma Form 1120 with Form 5472 attached.

Additionally, if in the future my individual-level income is deemed to have ECI, but if there is no permanent establishment as defined under the U.S.-China Income Tax Treaty, I could utilize the treaty. When filing Form 1040-NR, I would attach Form 8833 to cite the treaty and claim exemption from tax.

美国 LLC 报税名词解释：给独立开发者的税务入门

hi@rokcso.com (rokcso) — Fri, 06 Mar 2026 10:00:00 +0800

🔄 English

非美国居民的 SMLLC 进行 IRS 税务申报要提交哪些表？

⚠️ 注意：

以下所有名词解释都不是 100% 完整全面的，真正的完整全面可能只有去翻法典，我会省略一些个人认为对于当前我这种「Foreign-owned U.S. DE 的税务申报」相对不重要的信息或者例外，比如 Form 1040 的变体表不止下文提到的几种、不是所有外国公民在判定是否为 NRA 时都需要进行实质居留测试等等；
另外如果再考虑中美所得税协定的内容，情况可能会变得更为复杂，我已经有点难以理清了……所以暂时跳过。等我真的遇到被判定有 USTB、有 ECI 且需要在美国缴纳税款时再研究如何使用中美所得税协定来豁免税款（很有可能不会遇到）。

名词解释

Disregarded entity (DE)

被忽略实体。指在美国所得税层面下，不被视为可与其所有者分离的独立实体。

一般原则：作为 DE，其收入和支出在美国所得税层面下会「穿透」给其所有者，理论上由该所有者申报个人所得税即可（用 Form 1040）。

关键例外：根据美国税法第 6038A 节的要求，Foreign-owned U.S. DE 会被视为一个独立的公司，用于履行特定的申报义务，所以，Foreign-owned U.S. DE 需要由公司申报公司所得税（用 Form 1120），且必须附上 Form 5472。

Foreign-owned U.S. DE

外资美国被忽略实体。指完全由外国个人拥有的美国国内被忽略实体。

一个由非美国税务居民个人 100% 持有的美国怀俄明州 SMLLC 就是一个典型的 Foreign-owned U.S. DE。

NRA

全称 Nonresident Alien（非居民外国人），是美国税法中用于界定个人税务身份的概念，特指那些不满足美国税务居民标准的外国公民。

判定标准依据以下两项测试的反向结果（即两项测试都不通过则为 NRA）：

绿卡测试：如果个人在纳税年度内的任何时间都不是美国合法永久居民（即未持有绿卡），则不通过测试
实质居留测试：如果个人在纳税年度内不满足以下任一条件，则不通过测试
- 本年度在美国境内停留累计超过 31 天
- 本年度及过去两年内，按加权公式计算（本年度累计停留天数 + 去年累计停留天数 / 3 + 前年累计停留天数 / 6）在美国停留的总天数未超过 183 天

ECI

全称 Effectively Connected Income（有效关联收入或实际相关收入），指与非美国居民纳税人在美国境内从事的贸易或业务直接相关并来源于美国境内的收入。

核心判定逻辑：首先判定是否在美国境内从事贸易或业务（USTB，U.S. Trade or Business），然后再界定哪些来自美国境内的收入与此业务存在有效关联。

如果存在 ECI 就需要缴纳联邦所得税，个人提交 Form 1040，公司提交 Form 1120，但是由于 SMLLC 属于 DE，收入「穿透」给个人，所以需要个人提交 Form 1040（或其变体表）。

但是公司也需要在公司层面履行独立的申报义务，提交 Form 1120，如果是 NRA 持有的 SMLLC 则需要提交形式上的 Form 1120 并附上 Form 5472。

Form 1040

全称 U.S. Individual Income Tax Return（美国个人所得税申报表），是 IRS 要求符合条件的纳税人每年提交的联邦个人所得税申报表。

主要供美国税务居民使用，包括美国公民、绿卡持有者以及通过「实质居留测试」被认定为居民的外国人（非 NRA）。

在标准版 Form 1040 之外，还有一系列变体：

Form 1040-SR：专为 65 岁及以上纳税人设计的可选表格
Form 1040-NR：专为非居民外国人设计的用于申报其美国来源收入。当非居民外国人在美国有收入时，必须使用此表格而非标准 Form 1040
Form 1040-X：用于修正已提交的 Form 1040、Form 1040-SR 或 Form 1040-NR

在填报 Form 1040 时，通常还需要附上各种附表来提供额外详细信息，比如：

Schedule C：用于报告自营职业或独资企业的利润或亏损
Schedule A：用于报告逐项扣除额，如医疗费用、州税、房贷利息和慈善捐款
Schedule B：用于报告利息和股息收入
Schedule D：用于报告资本利得和损失

Form 1120

填写参考：非美国居民的 US LLC 税务申报：Form 1120 填写指南

全称 U.S. Corporation Income Tax Return（美国公司所得税申报表），是 IRS 要求符合条件的公司实体每年提交的联邦公司所得税申报表。

作为 C 公司纳税或者通过提交 Form 8832 选择被视为 C 公司纳税的其他形式的公司以及由非美国人或实体持有的美国被忽略实体（Foreign-owned U.S. DE）都需要提交 Form 1120。

但是 Foreign-owned U.S. DE 提交 Form 1120 并非因为该实体需要像 C 公司一样缴纳所得税，而是为了履行其特别的信息申报义务，并且 Foreign-owned U.S. DE 提交的 Form 1120 只是 Pro Forma 形式，只需要填写基本信息即可，不需要填写任何财务数据。

Foreign-owned U.S. DE 在提交 Pro Forma Form 1120 时还必须附上 Form 5472，用于报告其与外国关联方的交易信息。其实该 Pro Forma Form 1120 主要是作为 Form 5472 的「封面」，满足形式要求，真正的重点是 Form 5472。

Form 5472

填写参考：非美国居民的 US LLC 税务申报：Form 5472 填写指南

全称 Information Return of a 25% Foreign-Owned U.S. Corporation or a Foreign Corporation Engaged in a U.S. Trade or Business（美国 25% 外资控股公司或在美国从事贸易或业务的外国公司信息申报表），是 IRS 要求特定公司提交的一份信息申报表。

其本身并非用于计算和缴纳税款的税表，而是 IRS 监控和追踪跨境关联交易信息的工具。即使公司没有收入、没有税务义务，也必须提交，如果不提交，每次最低 $25,000 罚款。

总结

我们只需要将报税分成两条线来分析，个人和公司，两者相互独立但是又有一定关联。

首先对于个人，由于我是非美国居民（NRA），且没有 ECI，所以不用申报个人所得税，即不用提交 Form 1040-NR。

其次对于我的美国 LLC，是 Foreign-owned U.S. DE，所以公司所得税「穿透」到个人，理论上公司不用申报，由个人申报，但是个人是 NRA 且没有 ECI，所以个人也不用申报。

但是由于美国税法第 6038A 节的要求，Foreign-owned U.S. DE 有特别的申报义务，但是做了简化，不用提交标准的 Form 1120，而是提交形式上的 Form 1120 并附上 Form 5472。

另外如果我个人层面的所得税在未来被判定为有 ECI，但是如果没有中美所得税协定中规定的常设机构，则可以利用中美所得税协定，在提交 Form 1040-NR 的同时附上 Form 8833 引用协定豁免缴纳税款即可。

Mercury 企业账户申请全流程和审核经验分享

hi@rokcso.com (rokcso) — Fri, 27 Feb 2026 10:00:00 +0800

我的美国公司的 EIN 终于申请下来了，现在开始开通 Mercury 企业账户。经历了 2 次补充审核资料，整体不到 2 天就审核通过了。

本文将分享申请全流程和审核经验。

申请过程

注意：具体流程或者页面显示内容可能并非 100% 一致，但是核心流程节点以及问题处理思路是值得参考的。

前提条件：

美国公司
EIN
护照

注册账号

这一步核心是验证邮箱注册 Mercury 账号，后续账户申请以及其他账户相关操作都是关联在这个账号下面的。关于账号邮箱，有看到一些文章说需要用企业邮箱，但是我使用的是 Gmail 邮箱，依然没有问题。

首先访问 Mercury 官网，点击「Open Account」。

🎁 通过该链接 👆 申请福利：

在 90 天内入金 $10,000 可获得 $250 奖励

可以跳过审核队列，获得快速审核

填写姓名，一定真实姓名，中文则转拼音，参考护照上的英文名。

输入邮箱并设置密码，选择 Account type 为「Business」。

稍等一会邮箱应该会收到一封邮件要求验证邮箱地址。

完成邮箱地址验证后返回账户申请页面填写公司信息。

填写公司信息

首先输入公司名称，注意看页面提示 This will appear on your Mercury account, but doesn’t have to be your legal or trade name (you’ll add that later).，即这个名称只在 Mercury 内部使用，不必是公司法定名称，并且后续可以更改。但是也建议和公司法定名称保持一致。

然后设置 Mercury callsign，可以理解为代号或者用户名，且也只在 Mercury 内部使用。但是全 Mercury 唯一，不能和别的账号冲突，且后续无法更改。

然后选择 Is your company any of the following?，通常选择「None of the above」。

继续填写公司信息，这里：

Legal business name：需要和公司法定名称完全一致，参考公司成立文件
Country of incorporation：选择公司注册的国家「United States」
Phone number：可以使用 +86 手机号码
Company website：虽然为选填，但是建议填写一个看上去相对正式的公司网站
Employer Identification Number：如实填写
Industry：如实选择
Company type：如实选择
Company description：如实填写（AI 生成）
Major investors：选填，一般没有可留空

然后填写公司地址，注意需要填写公司法定地址，如果是通过注册代理机构注册的公司，注册代理机构提供的公司地址也是可用的，可以参考公司成立文件。

然后填写公司物理地址，即公司日常运营、办公或公司创始人个人居住的地址，不必和公司法定地址一致，但一定要真实可验证，中国地址也是可以的，中文则转拼音。

填写个人信息

然后填写公司所有权（人）信息，Single-Member LLC 就填写自己的个人信息即可。

姓、名：如实填写，中文则转拼音，参考护照上的英文名
Email：如实填写，可以和注册账号的邮箱一致
Job title：可选 Founder
Ownership percentage：可填 100%

注意这一页填写完成后点击「Continue」继续填写个人信息。

Citizenship status：选 Non-Resident
Phone number：可以使用 +86 手机号码
Date of birth：如实填写
Residential address：居住地址

由于刚刚的公司物理地址填写的就是个人居住地址，所以可以勾选 Residential address is the same as company physical address，如果不是则自行如实填写即可。

Identification：需要使用手机拍摄护照（建议使用护照而不是其他身份证件）首页并上传

点击「Verify Identity」会出现一个二维码，用手机扫码进入拍照页面，如果进入拍照页面失败则可以在申请页面手动选择文件上传护照照片。

上传护照后还需要使用设备摄像头自拍一张，也有可能需要配合要求点头摇头。

Professional social media presence：选填

PS：写这篇文章时才注意到要求的是 Professional 的社交媒体链接，一般推荐使用 LinkedIn，而不是 X。😅

填写完成后点击「Save」，然后 Who has the primary responsibility to control, manage, or direct the company’s business? 处选择刚刚填写的个人信息，再勾选下方声明信息后点击「Next」。

上传公司文档

这一步需要将公司成立文件和 EIN 证明文件上传给 Mercury，但是 Mercury 也有可能自动完成验证，则不需要上传，直接「Next」即可。

一般在公司 EIN 申请成功后一两周再申请 Mercury 则不需要手动上传相关文件。

填写账户使用声明

可以直接参考下图选择。

需要注意 Where will your first deposits come from? 问的是你的首笔资金来源，有些文章提到选择 Self 可能需要额外验证，选择 Revenue 则不需要，但是我这次申请选择的 Revenue 实际也要求验证收入来源，所以这里各位可根据实际情况或者提供验证文件的难易程度自行判断选择。

这里也是我后续需要两次补充审核资料的关键。

接下来验证物理地址，我使用的是招商银行信用卡账单，其中姓名和地址都是中文，没有英文翻译，但是 Mercury 其实也能自动识别，推测是直接转拼音。所以可见识别判定结果中地址验证无误，但姓名识别判定不一致，因为我在 Mercury 填写的姓名是 San Zhang，信用卡账单中的姓名转拼音是 Zhang San。

当然这里验证不通过并不影响申请流程继续进行。

最后下方 Do you think you’ll be using your Mercury account for any of these things? We’ll note these down to reduce potential follow-up later 选择「None of the above」后点击「Review Your Application」。

最后再 Review 一遍自己的申请信息，确认无误后最下方勾选同意协议后点击「Submit Application」。

等待审核 & 补充资料

提交申请后进入这个页面，可能会要求 Submit additional info，也有可能要求等待 In review，还有可能直接 Account ready。

在这个页面等待审核期间可能会要求你进行一些设置操作，基本都可以跳过，可以自行看页面提示。

如果被要求补充资料，Mercury 是会邮箱提醒的，错过了这个页面可以翻翻邮箱。

第一次补充资料

我第一次被要求补充 Revenue 相关证明资料（推测是由于上面账户使用声明中选择了 Revenue 为首笔资金来源），以及被要求补充地址证明资料（推测是由于刚刚地址验证时姓名没有验证通过）。

解题思路：关于 Revenue 主要是需要证明首笔资金来源是真实存在的，如果首笔资金来源是 Revenue 就提供相关收入证明，如果没有相关收入证明则可以提供一些产品信息告诉 Mercury 你有能力通过 Revenue 获得首笔资金。如果首笔资金来源是 Self 就提供个人收入证明告诉 Mercury 你个人能提供首笔资金。

关于地址验证则帮助 Mercury 判断你的地址、姓名是真实的。

我提交了什么？

关于 Revenue 我和 AI 一起写了一个文档（提交时翻译为英文并转 PDF 上传），介绍我公司的产品（网站地址、体验账号、演示截图）、用户量访问量等后台数据截图、Google AdSense 等后台截图，用户、客户沟通邮件截图等。

关于地址验证我也和 AI 一起写了一个文档（提交时翻译为英文并转 PDF 上传），解释了中文姓名、中文姓名拼音和英文姓名在格式上的差异，说明 San Zhang = Zhang San，并且提供护照、驾驶证等图片佐证姓名问题，并再次提供了招商银行信用卡账单，添加了一些英文标注帮助 Mercury 理解中英文姓名和地址的对应关系，甚至附上了维基百科链接以供参考。

第二次补充资料

等了大概 1 天，我再次被要求补充资料，首先要求阐述我的目标客户以及公司主要服务哪些行业，让 AI 了解我的产品后帮我撰写了一下，注意这里有字数限制，一定要简明扼要且真实。

然后依然要求我上传 Revenue 相关证明资料，但是这次的提示文案非常清晰的指出：我似乎选择了收入作为公司的资金来源，但是没有提供有效的文件来验证资金来源。并且最后提供了一个 I don’t have this document 的选项（第一次补充资料时是没有的），明确告知如果我没有这些文件，请告知 Mercury 我为何不能提供资金证明。

由于第一次补充资料我已经试图证明我有收入作为资金来源了，但是 Mercury 依然让我补充，所以这次我直接选择 I don’t have this document，然后填写原因，大意：

我第一次补充资料中提供了公司部分产品、数据、客户往来截图，但是我无法提供正式文件，因为：

广告平台为自动结算，没有签署合同
产品用户都是 C 端用户，我还没有打通收款能力，只能通过聊天工具收款，没有合同或支付平台（Stripe 等）的流水证明
B 端客户正在洽谈中，还没有签署合同
公司已有多款产品上线，并有真实用户，正在产生收入

这次补充资料后等待了几个小时我的开户申请就审核通过了。🎉

总结

Mercury 的审核的主要目的是验证你的公司以及公司的业务的真实性，遇到审核问题就按照这个思路去应对即可。

译> 我如何使用 Claude Code

hi@rokcso.com (rokcso) — Tue, 24 Feb 2026 10:00:00 +0800

我目前使用 Claude Code 的方式基本遵循「规划 –> 实施」的工作流，但是每一个环节的具体执行上其实还不够到位，我用过 Claude Code 内置的规划模式，也用过 OpenSpec 这种比较「重」的规划模式，感觉 Boris Tane 所分享的这种工作流是介于二者之间的恰到好处，值得尝试。

除了在规划阶段投入精力，及时止损也很重要，不要在投入太多精力让 Claude Code 修复它之前产出的错误结果，直接撤销从头再来通常更为高效。

本文翻译自 How I Use Claude Code，作者 Boris Tane

译文由 AI 翻译，rokcso 修正

我使用 Claude Code 作为主力开发工具已有大约 9 个月了，最终形成的工作流与大多数人使用 AI 编程工具的方式截然不同。多数开发者习惯于输入提示词、偶尔启用规划模式、修补错误、循环往复。更极端的用户则热衷于缝合各种技术黑话 —— 拉尔夫循环、MCP 协议、Gas Town（还记得这些吗？）等等。但无论是哪种方式，一旦涉及复杂场景便会土崩瓦解，产出的结果往往杂乱无章且难以维系。

我将要介绍的工作流有一个核心原则：在审查并批准书面方案之前，绝不允许 Claude 编写代码。这种规划与执行相分离的原则是我实践中最关键的突破。它不仅避免了无效劳动，让我始终掌控架构决策主导权，更重要的是，相比直接生成代码，这种模式能用更少的 token 消耗产出质量显著提升的成果。

graph LR
    A["研究"] --> B["规划"]
    B --> C["注释"]
    C --> | 重复 1-6x | C
    C --> D["任务清单"]
    D --> E["实施"]
    E --> F["反馈与迭代"]

第一阶段：研究

每个有价值的任务都始于一条深入研究指令。我会要求 Claude 在开展任何实际操作前，彻底理解代码库的相关部分。关键在于：所有研究发现必须写入可持续维护的 Markdown 文档，而绝不仅仅是聊天窗口中的临时性文字摘要。

深入阅读这个文件夹，彻底理解其工作原理，了解其功能以及所有具体细节。完成之后，将你的学习成果和发现详细记录在 research.md 文档中

深入研究通知系统，彻底理解其工作原理，并撰写一份详细的 research.md 文档，包含关于通知工作原理的所有信息

深入研究任务调度流程，彻底理解其工作原理，寻找潜在的错误。系统中确实存在错误，因为它有时会运行本应取消的任务。继续研究流程，直到找到所有错误，不要停止，直到所有错误被发现。完成后，在 research.md 中详细记录你的发现

注意这些措辞：「深度地」、「详细地」、「关注细节」、「全面地」。这不是无关紧要的。如果没有这些词，Claude 只会浅尝辄止。它可扫读文件，仅在函数签名层面了解其功能，然后跳过。你必须明确表示不能只做表面阅读。

书面文档（research.md）至关重要。这并非为了让 Claude 完成作业般的形式主义，而是我进行审查的基准界面。通过阅读这份文档，我能验证 Claude 是否真正理解了系统架构，并在制定规划前及时纠偏。若前期研究有误，后续规划必将出错，最终实现自然也会失败。输入的是垃圾，输出自然也是垃圾。

这正是 AI 辅助编程中最需要警惕的失败模式，问题并非出在语法错误或逻辑缺陷，而在于那些孤立运行正常却破坏系统整体性的实现。比如某个函数忽略了现有的缓存层，一次数据迁移未遵循 ORM 的规范，或是新增 API 端点重复实现了既有逻辑。而前期研究阶段正是杜绝此类问题的关键防线。

第二阶段：规划

在我审阅完研究报告后，会要求在一个独立的 Markdown 文件中提供详细的实施方案。

我想构建一个新功能（名称和描述），该功能扩展系统以执行（业务成果）。编写一个详细的 plan.md 文档，概述如何实现此功能。包含代码片段

列表接口应支持基于游标的分页，而非偏移量。请编写一份详细的 plan.md，阐述如何实现此功能。在提出修改建议前，务必阅读源文件，并依据实际代码库制定计划

生成的方案始终包含以下要素：详细的方法说明、展示具体修改的代码片段、涉及变更的文件路径，以及相关的考量因素与利弊分析。

我习惯使用自己的 .md 规划文档，而非 Claude Code 内置的规划模式。内置的规划模式实在难用。我的 Markdown 文件能让我完全掌控，既能在编辑器中自由修改，又可添加行内注释，更重要的是它能作为实际成果永久存储在项目里。

我有个常用的技巧：当需要开发独立功能时，如果曾在开源项目中见过优秀实现，我会将参考代码与需求说明一并提交。比如要实现可排序 ID 功能，就直接粘贴某个项目的 ID 生成代码，附上说明「这是别人实现可排序 ID 的方案，请据此撰写 plan.md 说明如何采用类似方案」。实践表明，当 Claude 拥有具体参考实现而非从零设计时，工作效果会显著提升。

不过，规划文档本身其实不是重点。真正的精髓在于后续的展开。

注释循环

这是我工作流中最具特色的环节，也是我个人价值贡献最集中的部分。

graph TD
    A[Claude 编写 plan.md] --> B[我在编辑器中审阅]
    B --> C[我添加行内注释]
    C --> D[将文档重新发给 Claude]
    D --> E[Claude 更新 plan.md]
    E --> F{满意？}
    F -->|No| B
    F -->|Yes| G[请求任务清单]

当 Claude 输出规划方案后，我会在编辑器中打开文档，直接添加行内注释。用来修正不合理的假设、否决某些实现路径、增加技术约束条件，或是补充 Claude 所欠缺的领域知识。

注释的篇幅差异极大。有时仅需两三个字，比如在 Claude 标记为「可选」的参数旁写上「必填」；有时则需一大段话，阐释某个业务逻辑的来龙去脉，或是直接粘贴代码片段示范预期的数据结构。

以下是我实际添加注释的几个真实样例：

使用 drizzle:generate 来处理数据库迁移，而不是直接编写原始 SQL—— 这是 Claude 缺乏的领域知识
不，这应该是 PATCH 请求，而不是 PUT 请求 —— 纠正一个错误的假设
我们不需要缓存，直接删除这个部分 —— 拒绝一个提案
队列消费者已经处理重试，因此这个重试逻辑是多余的。直接删除它，让程序直接失败。 —— 解释为什么某事应该改变
这是错误的，可见性字段需要位于列表本身上，而不是单个项目上。当一个列表是公开的，所有项目都是公开的。相应地重新构建模式部分。 —— 重定向整个计划的一部分

然后我将文档重新发给 Claude：

我在文档中添加了几条注释，请处理所有注释并相应更新文档。暂不实现

这个循环重复 1 到 6 次。显式的「暂不实现」是必不可少的。没有它，Claude 会立刻跳到编写代码，只要它认为规划足够好。只要在我确认它足够好之前，它都还不够好。

为什么效果如此出色

这个 Markdown 文件在我和 Claude 之间是共享可变状态。我可以按自己的节奏思考，精确标注错误之处，重新参与讨论而不丢失上下文。我并非试图在聊天消息中解释所有内容，而是在文档中直接指出问题所在并写出更正。

这本质上与试图通过聊天消息来指导实施是不同的。这个规划是一个结构化、完整的规范，我可以全面地审查。聊天对话是我需要滚动查看才能重建决策的内容。规划每次都更好。

经过三轮「我添加注释，更新计划」可以将一个通用的实施规划转变为与现有系统完美契合的规划。Claude 在理解代码、提出解决方案和编写实现方面非常出色。但它不了解我的产品优先级，不了解我的用户的痛点，也不了解我愿意做出的工程权衡。注释循环是我注入这种判断的方式。

任务清单

在实施开始前，我总会先要求将任务分解得尽可能详细：

在规划中添加一份详尽的任务清单，涵盖所有阶段及完成规划所需的各项具体任务，暂不执行

这会创建一个清单，用作实施过程中的进度跟踪器。Claude 会随着进展自动标记项目为已完成，因此我随时可以查看规划，准确了解当前进度。这对于进行数小时会话的场景尤其有用。

第三阶段：实施

当规划准备就绪后，我会下达实施指令。我已经将其精炼成一个标准提示词，并在各个会话中重复使用：

全面实施。当任务或阶段完成后，请在规划文档中将其标记为已完成。不要停止，直到所有任务和阶段都完成。不要添加不必要的注释或 jsdocs，不要使用任何或未知的类型。持续运行类型检查，确保不会引入新的问题。

这个提示词包含了所有关键内容：

全面实施：严格按照计划完成所有内容，不挑拣部分
在规划文档里标记为完成：规划是衡量进度的基准
不停止，直到所有任务和阶段都完成：流程中不暂停确认
不要添加多余的注释或 jsdocs：使代码保持简洁
不要使用任何或未知的类型：坚持严格的类型规范
持续进行类型检查：在项目最终完成前尽早捕捉问题

我几乎在每次实施过程中都使用这个措辞（略有变化）。当我说「全面实施」时，所有决策都已做出并验证。实施变得机械而非创造性，这是有意为之。我想让实施过程变得枯燥乏味，创造性的工作发生在注释循环。一旦规划正确，实施就应该是直截了当的。

如果没有规划阶段，Claude 通常会过早地做出一个看似合理但实际上错误的假设，并在此基础上进行大约 15 分钟的构建，然后我不得不逐一撤销这些更改。「不要立即实现」的防护措施可以完全避免这种情况。

实施过程中的意见反馈

一旦 Claude 开始实施规划，我的角色就从架构师转变为监督者。我的提示变得非常简洁。

graph LR
    A[Claude 实施] --> B[我审查/测试]
    B --> C{正确？}
    C -->|No| D[简洁的纠正]
    D --> A
    C -->|Yes| E{更多任务？}
    E -->|Yes| A
    E -->|No| F[完成]

规划注释可能是一个段落，但实施更正通常只是一句话：

你没有实现 deduplicateByTitle 这个函数。
你应在管理应用中构建设置页面，而不是主应用中，移动它。

Claude 对整个规划和当前会话都有全面的了解，因此只需简洁的更正即可。

前端开发是最需要不断迭代的部分。我通常在浏览器中测试，并迅速做出调整：

更宽
始终裁切
有 2px 的间隙

遇到视觉问题时，我有时会附上截图。一张表格错位截图比文字描述更能快速传达问题。

我也经常参考已有代码：

这个表格应该与用户表格完全一致，表头、分页和行密度都应相同。

这种方法比从零开始描述一个设计要精确得多。成熟代码库中的大多数功能都是基于现有模式的变体。因此，新的设置页面应该与现有的设置页面保持一致。通过参考现有页面，可以传达所有隐含的要求，无需详细说明。Claude 通常会在进行更正之前读取参考文件。

当事情出现偏差时，我不会尝试去修补。我会回滚并重新规划，通过舍弃 Git 的更改：

我已经恢复了一切。现在我只想要让列表视图更简洁，其他什么都不需要。

进行回滚后缩小工作范围，通常比试图逐步修正错误的方法效果更好。

保持在掌控之中

虽然我把实施任务委托给 Claude，但我从不给它完全的自主权去决定构建什么。我在 plan.md 文档中负责绝大部分的主动指导。

这很重要，因为 Claude 有时会提出技术上正确但对项目不合适的解决方案。或许这个方法过于复杂，或者它改变了其他系统部分依赖的公共 API 签名，或者它选择了一个更复杂的选项，而一个简单的选项就足够了。Claude 没有关于整个系统、产品方向和工程文化的背景信息。

graph TD
    A[Claude 提出提案] --> B[我评估每一项]
    B --> C[原样接受]
    B --> D[修改提案]
    B --> E[跳过/移除]
    B --> F[覆盖技术选择]
    C --> G[精炼的实施范围]
    D --> G
    E --> G
    F --> G

在提案中进行挑选：当 Claude 提出多个问题时，我会逐一处理：「第一个问题直接用 Promise.all 就行，别搞太复杂；第三个问题单独提取成函数，提升可读性；第四个和第五个忽略掉，不值得为此增加复杂度。」。我正基于当前最紧要的知识点，逐项做出决策。

范围裁剪：当规划包含锦上添花的功能时，我会果断削减。「将下载功能从计划中移除，我现在不想实现这个。」。这能有效防止范围无限制扩大。

保护现有接口：当我明确某些内容不应更改时，我会设置硬性约束：「这三个函数的签名不应更改，调用方必须适配，而非修改库本身。」

覆盖技术选择：有时我有特定的偏好（这是 Claude 无法知晓的），比如*「使用这个模型而非那个」或「使用这个库的内置方法而非编写自定义方法」*。快速、直接的覆盖操作。

Claude 负责具体实施，而我负责关键决策。规划预先就明确方向，选择性指导则处理实施过程中出现的小细节。

单个长时间会话

我倾向于在单个长时间会话中完成研究、规划和实施，而非拆分为多个独立会话。一次会话可能从深度阅读某个文件夹开始，经过三轮规划注释，然后执行完整实施方案，全程在连续对话中一气呵成。

实际上我并未遇到像大家说的那样上下文窗口占用超 50% 后的性能衰减。因为当我说「全面实施」时，Claude 早已在整个会话中持续构建认知：在研究阶段阅读文件，在注释循环完善思维模型，并吸收我提供的领域知识修正。

当上下文窗口满载时，Claude 的自动压缩机制会保留足够上下文以保持进程连贯。而作为持久性产物的规划文档，能在压缩过程中完整保留全部信息精度。我可以在任意时间点指引 Cluade 查阅该文档。

一句话概括

深度阅读，制定规划，反复注释直至计划完善，然后放手让 Claude 连续全面实施，过程中进行类型检查。

仅此而已。无需魔法提示词，无需复杂的系统指令，无需奇技淫巧。只需要一套将思考与执行分离的规范流程。前置研究能防止 Claude 做出无知的改动，详细规划能避免其错误修改，注释循环则注入我的判断力。而在所有决策敲定后，一条实施指令即可让它心无旁骛地持续运转。

试试这套工作流，你会惊讶于从前没有注释规划文档作为缓冲时，自己究竟是如何用编程 Agent 完成任何项目。

译> 我的 AI 应用之路

hi@rokcso.com (rokcso) — Mon, 09 Feb 2026 10:00:00 +0800

本文翻译自 My AI Adoption Journey，作者 Mitchell Hashimoto

译文由 AI 翻译，rokcso 修正

我的经验是，任何有意义的工具，都要经历三个阶段方能掌握：（1）低效适应期（2）基本应用期（3）革新蜕变期。

由于已有得心应手的工作流，我往往要逼着自己突破前两个阶段。尝试新工具总像额外负担，虽心有不甘，但为成为全面发展的多面手，我总会坚持投入。

这是我探索 AI 工具价值的历程，以及正在探索的新可能。在当下众声喧哗的 AI 热潮中，我希望能以这份审慎从容的思考，记录自己对 AI 认知的演进轨迹。

本文全程手写，字字皆出己思。在此强调似乎多余，但鉴于主题特殊性，特此说明。

第一步：告别聊天机器人

请立即停止试图通过聊天机器人（如 ChatGPT、网页版的 Gemini 等）完成实质性工作。这类工具确有价值，也是我日常 AI 工作流的一部分，但它们在编程领域的效用极其有限，因为你本质上是在赌训练数据能恰好生成正确结果，而纠错过程更需人工反复指正，效率低下。

我相信多数人的 AI 初体验都始于聊天界面，编程初尝试也是让聊天机器人代写代码。

在我仍是 AI 怀疑论者时，曾将 Zed 编辑器命令面板的截图粘贴至 Gemini，要求其用 SwiftUI 复刻，当它在数秒内交出近乎完美的成品时，确实令我震撼。如今 Ghostty for macOS 的默认命令面板，正是在 Gemini 生成的代码基础之上微调而成。

但当我试图在其他任务中复现这种成功时，结果往往令人失望。尤其在已有项目中，聊天机器人频繁输出低质结果，让我陷入复制粘贴代码和命令输出的繁琐循环。这种模式效率之低下，明显不如亲自动手。

要真正释放价值，必须转向使用智能体。这是行业公认的术语，指具备循环交互能力并能触发外部行为的 LLM 系统¹。一个合格的智能体至少应具备：文件读取、程序执行和 HTTP 请求发起能力。

第二步：复刻你的工作流程

我接下来的尝试是使用 Claude Code。长话短说：初期体验并不惊艳。产出质量不尽人意，总觉得需要逐行修改，耗时甚至超过亲手完成。尽管研读了技术博客、观看演示视频，仍未见其精妙之处。

但我没有放弃，而是强制自己用智能体复现所有手动提交的代码。字面意思地将同一项工作重复完成两次。先手动实现，再引导智能体产出功能与质量完全相同的结果（当然不会让它参考我的手写代码）。

这个过程堪称煎熬，因为它违背了「高效完成」的基本诉求。但多年使用非 AI 工具的经验告诉我，磨合期的阵痛在所难免，唯有全力尝试后才能得出经得起推敲的结论。

正是在这种刻意练习中，专业认知逐渐形成。我很快从第一性原理出发，验证了他人已提出的观点，而亲身体验带来的理解更为深刻：

任务拆解：将复杂任务拆分为清晰可行的子任务，避免试图「一步登天」
规划分离：模糊需求应先进行规划，再执行实施
自检机制：赋予智能体验证自身工作的能力，它往往能自主修正错误并防止倒退

更重要的是，我摸清了当时智能体的能力边界：擅长什么、不擅长什么，以及如何在其优势领域达成目标。

这一切带来显著的效率提升，以至于我开始自然而然地使用智能体，虽然尚未感觉更快（因为多数时间仍在监督执行），但至少不再迟滞。

特别需要强调的是：效率提升部分源于懂得何时不使用智能体。明知会失败仍强行调用纯属浪费时间，而具备这种避坑意识本身就是一种节约时间²。

至此，智能体已足够好用，我乐意将其纳入工作流，虽未实现净效率增益，但作为工具已令我满意。

第三步：日结智能体

为了进一步提升效率，我开始尝试新模式：每天留出最后 30 分钟，启动一个或多个智能体任务。我的假设是：如果智能体能在我无法工作的时间段取得进展，或许能实现效率增益。本质上是将生产力从「拥有的时间」延伸到「本不工作的时间」。

与上一阶段类似，初期尝试既无成效又令人烦躁。但我很快发现了适合此模式的三大场景：

深度调研任务：让智能体系统梳理某个技术领域，例如检索特定语言中符合某许可证类型的所有库，并为每个库生成多页评估报告，涵盖优劣分析、开发活跃度、社区反馈等。
并行探索概念：同时启动多个智能体验证不同设想。我不期望它们直接产出可交付成果，但能为次日工作揭示潜在盲区。
Issue 与 PR 分类：智能体擅长使用 GitHub CLI 工具，我编写脚本批量启动并行任务进行分类。仅允许生成报告而非直接回复，次日可根据报告优先处理高价值或低耗时任务。

需要说明的是，我并未像某些实践者那样让智能体整夜循环运行。多数任务能在半小时内完成。但关键在于：工作日下午的我通常处于精力低谷，效率低下，此时转为启动智能体任务，反而能为次日早晨提供「热启动」，让我更快进入工作状态。

至此，我开始感受到 AI 带来了超越以往的产能提升，尽管幅度尚微，但已足够令人欣喜。

第四步：外包「稳赢」任务

此时，我已经非常清楚 AI 擅长和不擅长哪些任务。对于某些特定任务，我能高度确信 AI 能给出基本正确的解决方案。因此，我旅程的下一步是：在我处理其他任务的同时，让智能体包揽所有那些它擅长的工作。

更具体地说，我每天会先查看前一夜分类智能体的结果，手动筛选出那些智能体几乎肯定能完美解决的 Issue，然后让它们在后台运行（一次一个，不并行处理）。

与此同时，我会去处理别的事情。我不会去刷社交媒体（和使用 AI 之前一样），也不会看视频等等。我会进入自己惯有的、AI 出现之前的深度思考模式，去处理我想做或必须做的任务。

这个阶段非常重要的一点是：关闭智能体的桌面通知。上下文切换的成本非常高。为了保持效率，我发现我的职责是掌控何时去打断智能体，而不是反过来被它打断。不要让智能体通知你。在你工作的自然间隙，切换标签页去检查它的进度，然后继续你的工作。

重要的是，我认为「处理其他任务」这一点有助于抵消广为人知的 Anthropic 关于技能形成的论文中提到的影响。这其实是一种权衡：你将任务委托给智能体，可能会影响你在这些任务上的技能形成，但同时你通过继续手动处理的任务，技能仍在自然地形成。

到了这个阶段，我已经坚定地处于「绝不可能再回到过去」的状态了。我感觉效率更高了，但即便没有，我最喜欢的一点是，我现在可以将编码和思考的精力集中在我真正热爱的任务上，同时又能妥善完成那些我不太喜欢的任务。

第五步：设计约束框架

有一点可能显而易见：当智能体首次就能产出正确结果，或者最差也只需极少修改时，其效率会大幅提升。实现这一目标最可靠的方法是，为智能体提供快速、高质量的工具，使其能自动判断对错。

我不知道业界对此是否有广泛接受的术语，但我逐渐称之为「约束框架」。其核心思想是：每当你发现智能体犯错时，就花时间设计一种解决方案，确保该智能体永不再犯同样的错误。这里我不需要创造新术语；如果已有其他术语，我很乐意采纳。

这主要体现在两种形式中：

改进隐式提示（AGENTS.md）。针对简单问题，比如智能体反复运行错误命令或使用错误 API，更新 AGENTS.md（或类似文件）。这里有一个 Ghostty 的示例。该文件中每一行都基于一次智能体的不当行为，而它几乎完全解决了所有这些问题。
实际的程序化工具。例如，用于截图、运行筛选测试等的脚本。这通常与 AGENTS.md 的更改配合使用，以让智能体知晓这些现有工具。

这就是我目前的状态。每当看到智能体做出不当行为时，我都会认真投入努力以防止它再次犯错。或者反过来，我正努力让智能体能够自我验证其行为是否正确。

第六步：保持智能体持续运行

在与第五步同步推进的同时，我还设定了一个目标：始终保持至少一个智能体在运行。如果没有智能体在运行，我会问自己：「现在有什么事情可以让智能体替我处理吗？」

我特别喜欢将这个目标与 Amp 的深度模式这类速度较慢但更善于思考的模型结合使用（该模式基本上就是 GPT-5.2-Codex），它可能需要超过 30 分钟来完成一些小改动。但好处是，它往往能产出非常出色的结果。

我（目前？）还没有运行多个智能体，也暂时不打算这样做。我发现，现阶段只运行一个智能体，对于我平衡两方面需求很合适：既能进行我喜欢的深度手动工作，又能照看我那位有点「笨拙」却又莫名高效的神秘机器人伙伴。

「始终保持智能体运行」这个目标目前仍然只是一个目标。可以说，目前在一个正常的工作日里，我大概能有 10% 到 20% 的时间有效地让一个智能体在后台运行。但我正在积极努力提升这个比例。

我不想为了运行智能体而运行智能体。我只在认为某项任务真正对我有帮助时才会启动它们。这个目标的部分挑战在于，需要改进我自己的工作流和工具，以便能持续产生高质量的、可以委托出去的任务。这一点，即使没有 AI，也同样重要！

当下

这就是我目前的处境。

通过这段旅程，我个人在使用现代 AI 工具方面已经取得了一些成功，并且我相信我正以一种基于现实的、审慎的态度来对待它。我其实并不太在意 AI 是否会永久存在³，我是一个软件工匠，仅仅因为热爱这份事业而想要创造东西。

整个领域发展如此之快，我敢肯定我很快就会回头看这篇文章，并嘲笑自己的天真。但是，正如人们所说，如果你不为过去的自己感到尴尬，那你可能并没有在成长。我只希望自己能朝着正确的方向成长！

我在这方面并无既得利益⁴，而且不使用 AI 当然也有其他合理的理由。我完全尊重任何人的个人决定。我写这些并不是为了说服你！我只是想和那些感兴趣的人分享一下我个人使用这些新工具的方法，并大致展示我通常是如何对待新工具的，无论是否与 AI 相关。

相较于对话模型，像 Opus 和 Codex 这样的现代编程模型在训练时就被专门设计为更倾向于使用工具。 ↩︎
由于模型迭代速度极快，我必须持续修正自己对此的原有认知。 ↩︎
但最让我深感忧虑的是，这对基础不扎实的初级开发者可能造成的技能养成缺陷。 ↩︎
我不受雇于任何 AI 公司，也未进行相关投资或提供咨询服务。 ↩︎